@uniweb/api 1.2.0 → 1.2.2

package/src/mock/definition.js

@@ -0,0 +1,119 @@
+/**
+ * A Model's definition, as the backend stores and answers it — lowered from a seed's
+ * declaration the way a registered schema is lowered (MEASURED 2026-10-14; `SCHEMA` in
+ * `../wire.js` is the shape).
+ *
+ * ⭐ **A field keeps what the backend keeps, and nothing else.** A key the backend's
+ * catalog does not hold for the field's kind never reaches a stored declaration — a
+ * schema carrying one is refused when it is registered — so the mock's definition
+ * leaves it out rather than show a form a rule no backend applies. The catalog, per
+ * kind, beside what every field may declare (`label`, `description`, `required`,
+ * `multiple`, `localized`, `compact`):
+ *
+ * | kind | its own keys |
+ * |---|---|
+ * | `string` · `text` | `max_length`, `languages`, `format` |
+ * | `int` | `min`, `max` |
+ * | `decimal` | `precision`, `scale`, `min`, `max` |
+ * | `date` | `format` — `year-month` or `year` |
+ * | `item_ref` | `options` (a schema's) → `section_uuid`; `entity_uuid` |
+ * | `entity_ref` | `model` (a schema's) → `model_uuid`; `model_uuids`, `contains`, `readable_with` |
+ * | `file` | `mime_types`, `max_size` |
+ * | `json` | `languages`, `format` |
+ * | `bool` · `datetime` · `secret` | none |
+ *
+ * And what moves: an `enum` becomes its section's `one_of` rule; `multiple: true` is
+ * `multi`; a nested section is a section of its own.
+ */
+
+/** The keys a kind declares beyond the ones every field may (see the table above). */
+const KIND_KEYS = {
+  string: ['max_length', 'languages', 'format'],
+  text: ['max_length', 'languages', 'format'],
+  int: ['min', 'max'],
+  decimal: ['precision', 'scale', 'min', 'max'],
+  date: ['format'],
+  item_ref: ['entity_uuid'],
+  entity_ref: ['model_uuids', 'contains', 'readable_with'],
+  file: ['mime_types', 'max_size'],
+  json: ['languages', 'format'],
+}
+
+/** Prose about a field — a plain string. */
+const DOC_KEYS = ['label', 'description']
+
+/** Modifiers any kind that supports them declares. */
+const MODIFIER_KEYS = ['localized', 'compact']
+
+/** A field's kind: its `type`, or a list's element type in the normalizer's `array` spelling. */
+export function kindOf(field) {
+  if (field?.type === 'array') return field.items?.type ?? 'json'
+  return field?.type ?? 'json'
+}
+
+/** Is this field a list — `multiple: true`, or the normalizer's `type: 'array'`? */
+export const isList = (field) => field?.multiple === true || field?.type === 'array'
+
+/**
+ * A field as the definition answers it: `{ key, required, multi, type: { id: -1, name,
+ * kind, data } }`, `data` its stored declaration.
+ *
+ * @param {string} key
+ * @param {object} field - the seed's declaration
+ * @param {{ section?: string|null, model?: string|null }} pins - an `item_ref`'s section
+ *   uuid and an `entity_ref`'s Model uuid, resolved by the caller
+ */
+export function fieldRow(key, field, pins = {}) {
+  const kind = kindOf(field)
+  const data = { key, kind }
+  if (field?.required === true) data.required = true
+  if (isList(field)) data.multi = true
+  for (const k of DOC_KEYS) if (typeof field?.[k] === 'string') data[k] = field[k]
+  for (const k of MODIFIER_KEYS) if (field?.[k] !== undefined) data[k] = field[k]
+  for (const k of KIND_KEYS[kind] ?? []) if (field?.[k] !== undefined) data[k] = field[k]
+  if (kind === 'item_ref' && pins.section) data.section_uuid = pins.section
+  if (kind === 'entity_ref' && pins.model) data.model_uuid = pins.model
+  return {
+    key,
+    required: data.required === true,
+    multi: data.multi === true,
+    type: { id: -1, name: kind, kind, data },
+  }
+}
+
+/**
+ * A section's rules: its own (a bare array, or `{ rules: [...] }`), then a `one_of` for
+ * each field that declares an `enum`, in field order.
+ *
+ * @param {object|null} section - the seed's declaration
+ * @param {Object<string, object>|null} leaves - its fields, by key
+ */
+export function rulesOf(section, leaves) {
+  const own = section?.constraints
+  const rules = Array.isArray(own) ? [...own] : Array.isArray(own?.rules) ? [...own.rules] : []
+  for (const [key, field] of Object.entries(leaves || {})) {
+    if (Array.isArray(field?.enum) && field.enum.length) rules.push({ kind: 'one_of', field: key, values: field.enum })
+  }
+  return rules
+}
+
+/** What a section's `other_data` holds: what the schema declares of the section. */
+export function otherDataOf(section, { appendOnly = false, nests = false } = {}) {
+  const other = {}
+  for (const k of DOC_KEYS) if (typeof section?.[k] === 'string') other[k] = section[k]
+  if (appendOnly) other.append_only = true
+  if (nests) other.allow_self_nesting = true
+  if (typeof section?.date_field === 'string') other.date_field = section.date_field
+  return other
+}
+
+/**
+ * `options: '@scope/name/section/path'` — the Model named by its first two segments, and
+ * the section path after them — or null when it has the wrong shape.
+ */
+export function parseOptions(options) {
+  if (typeof options !== 'string') return null
+  const parts = options.split('/')
+  if (parts.length < 3 || !parts[0].startsWith('@')) return null
+  return { model: `${parts[0]}/${parts[1]}`, path: parts.slice(2).join('/') }
+}

package/src/mock/index.js

@@ -1,4 +1,4 @@
-import { AUTH, ENTITIES, MODELS, OFFERS, INVITATIONS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS, HANDOFF_REFUSAL, ELEVATION } from '../wire.js'
+import { AUTH, ENTITIES, MODELS, SECTIONS, OFFERS, INVITATIONS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS, HANDOFF_REFUSAL, ELEVATION } from '../wire.js'
 import { MockStore, isUuid, refuse } from './store.js'
 import { DEFAULT_SEED } from './seed.js'
 
@@ -17,6 +17,24 @@ export function printMail(message, url) {
  */
 const ADMIN_PAGE = '/admin'
 
+/**
+ * A page's cursor, opaque as the backend's is: hex of the JSON of where the page ended.
+ * Byte work by hand, so the mock stays free of Node's `Buffer`.
+ */
+const encodeCursor = (key) =>
+  [...new TextEncoder().encode(JSON.stringify(key))].map((b) => b.toString(16).padStart(2, '0')).join('')
+
+/** The key a cursor names, or null for one this mock did not hand out — "expired". */
+function decodeCursor(token) {
+  if (!/^(?:[0-9a-f]{2})+$/.test(token)) return null
+  try {
+    const key = JSON.parse(new TextDecoder().decode(Uint8Array.from(token.match(/../g).map((h) => parseInt(h, 16)))))
+    return Array.isArray(key) && key.length === 5 && key.every(Number.isFinite) ? key : null
+  } catch {
+    return null
+  }
+}
+
 const escapeHtml = (value) =>
   String(value).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c])
 
@@ -53,7 +71,7 @@ function adminPage(account) {
  *
  * ## Where it answers
  *
- * Its routes are the API's own — `/auth/me`, `/entities` — under whatever the
+ * Its routes are the API's own — `/auth/me`, `/entities`, `/sections` — under whatever the
  * site's `backend` address is. It accepts a request with the site's `/_api` prefix
  * still on, and one with an extra `/api` after it (how clients before 0.4
  * composed URLs), so it answers the same whether or not the server mounting it
@@ -69,9 +87,11 @@ function adminPage(account) {
  * account the backend's administration admits, so its Admin link answers — with a
  * redirect to a page of the mock's own, since the administration itself is not
  * modelled. An offer, claimed or bound by confirming its address, leaves its
- * invitations waiting, each to answer once. It does not model entitlements behind
- * `via`, nested sections, second factors, password rules, an offer's grants, what
- * joining an organization gives, or an organization withdrawing an invitation.
+ * invitations waiting, each to answer once. A field that picks from a list stores an
+ * item's uuid, checked against its list, and the list's items are read a page at a time
+ * from `/sections/{uuid}/items`. It does not model entitlements behind `via`, second
+ * factors, password rules, an offer's grants, what joining an organization gives, or an
+ * organization withdrawing an invitation.
  *
  * ## The mail it sends
  *
@@ -352,18 +372,52 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
       return model && store.maySeeSchema(model) ? json(200, store.schemaOf(model)) : notFound('model', name)
     }
 
+    // ── A Section's items ────────────────────────────────────────────────────
+    const listed = path.startsWith(`${SECTIONS}/`) ? path.slice(SECTIONS.length).match(/^\/([^/]+)\/items$/) : null
+    if (listed && method === 'GET') {
+      const bad = unexpected(q, [PARAM.entity, PARAM.parent, PARAM.field, PARAM.q, PARAM.locale, PARAM.cursor, PARAM.limit])
+      if (bad) return bad
+      const limit = int(q, PARAM.limit, PAGE.size)
+      if (limit === undefined) return badRequest('invalid parameter value')
+      if (!store.account) return unauthorized()
+      const sectionUuid = listed[1]
+      if (!isUuid(sectionUuid)) return badRequest(`invalid section uuid: ${sectionUuid}`)
+      const token = q.get(PARAM.cursor) || ''
+      const after = token ? decodeCursor(token) : null
+      if (token && !after) return badRequest('cursor expired, restart pagination')
+      for (const name of [PARAM.entity, PARAM.parent]) {
+        const value = q.get(name)
+        if (value && !isUuid(value)) return badRequest(`invalid ${name} uuid: ${value}`)
+      }
+      const found = store.sectionByUuid(sectionUuid)
+      if (!found) return notFound('section', sectionUuid)
+      const outcome = store.sectionItems(found.model, found.section, {
+        entity: q.get(PARAM.entity) || null,
+        parent: q.get(PARAM.parent) || null,
+        field: q.get(PARAM.field) || '',
+        q: q.get(PARAM.q) || '',
+        locales: locales(q),
+        after,
+        limit: Math.min(Math.max(limit, 1), PAGE.max),
+      })
+      if (outcome.problem) return answer(outcome)
+      const { next_cursor: next, ...rest } = outcome.body
+      return json(200, { ...rest, next_cursor: next ? encodeCursor(next) : null })
+    }
+
     // ── Entities ────────────────────────────────────────────────────────────
     if (path === ENTITIES || path.startsWith(`${ENTITIES}/`)) {
       const rest = path.slice(ENTITIES.length)
 
       if (rest === '' && method === 'GET') {
-        const bad = unexpected(q, [PARAM.model, PARAM.scope, PARAM.limit, PARAM.offset, PARAM.paginate, PARAM.locale, PARAM.includeDisabled])
+        // ⛔ No `include_disabled`: the backend refuses it, and lists a disabled entity like any other.
+        const bad = unexpected(q, [PARAM.model, PARAM.scope, PARAM.limit, PARAM.offset, PARAM.paginate, PARAM.locale])
         if (bad) return bad
         if (!q.get(PARAM.model)) return badRequest(`Missing required parameter: ${PARAM.model}`)
         const limit = int(q, PARAM.limit, PAGE.size)
         const offset = int(q, PARAM.offset, 0)
         const paginate = bool(q, PARAM.paginate, true)
-        if (limit === undefined || offset === undefined || paginate === undefined || bool(q, PARAM.includeDisabled, false) === undefined) {
+        if (limit === undefined || offset === undefined || paginate === undefined) {
           return badRequest('invalid parameter value')
         }
         const scope = q.get(PARAM.scope) || SCOPE.accessible

package/src/mock/schema-shape.js

@@ -148,6 +148,20 @@ function listElement(field) {
   return null
 }
 
+/**
+ * A section of the declaration by name — or by `parent/child` path for a nested one,
+ * declared as a field of `type: 'section'` inside its parent.
+ */
+function sectionAt(sections, path) {
+  const [first, ...rest] = String(path).split('/')
+  let at = sections[first]
+  for (const name of rest) {
+    const next = at?.fields?.[name]
+    at = next?.type === 'section' ? next : undefined
+  }
+  return at
+}
+
 /**
  * Is this section a multi section of the model's declaration?
  *
@@ -158,7 +172,7 @@ function listElement(field) {
 export function classifySection(decl, section) {
   const sections = decl?.sections
   if (!sections || typeof sections !== 'object') return null
-  const found = sections[section]
+  const found = sectionAt(sections, section)
 
   // ⭐ The debt list is consulted FIRST and is an exact `(model, section)` match, so
   // it can excuse a declared section whose records diverge as well as an undeclared
@@ -225,8 +239,80 @@ function satisfiesType(type, value) {
   }
 }
 
+/** The text kinds — what a `localized` value, a `max_length` and a search apply to. */
+const TEXT_TYPES = new Set(['string', 'text', 'html', 'markdown', 'email', 'url'])
+
+/** Characters, as the backend counts them — code points, not UTF-16 units. */
+const charCount = (s) => [...s].length
+
+/**
+ * A `date` at the precision its field declares, as the backend checks it (MEASURED 2026-10-14):
+ * `format: year-month` holds `YYYY-MM`, a month `01` to `12`; `format: year` holds `YYYY`; and
+ * with no `format`, a day the calendar has (`2024-5-3` passes, `2024-05` and `2024-02-30` do not).
+ */
+function isDateAt(value, format) {
+  if (format === 'year-month') return /^\d{4}-(0[1-9]|1[0-2])$/.test(value)
+  if (format === 'year') return /^\d{4}$/.test(value)
+  return isDate(value)
+}
+
+/** `YYYY-MM-DD`, a day the calendar has. */
+function isDate(value) {
+  const m = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(value)
+  if (!m) return false
+  const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])]
+  const day = new Date(Date.UTC(y, mo - 1, d))
+  return day.getUTCFullYear() === y && day.getUTCMonth() === mo - 1 && day.getUTCDate() === d
+}
+
+/**
+ * A `format` the backend checks, by its own rules — `email`: one `@`, something before it,
+ * a dotted domain after it, no space; `url`: a scheme, `://`, something after it, no space.
+ * ⚠️ `currency` is checked there too, against ISO 4217's codes, and not here. Every other
+ * `format` marks what the text is and checks nothing.
+ */
+function matchesFormat(value, format) {
+  if (format === 'email') {
+    const parts = value.split('@')
+    return parts.length === 2 && parts[0] !== '' && parts[1].includes('.') && !parts[1].startsWith('.') && !parts[1].endsWith('.') && !/\s/.test(value)
+  }
+  if (format === 'url') {
+    const at = value.indexOf('://')
+    return at > 0 && /^[A-Za-z0-9+.-]+$/.test(value.slice(0, at)) && value.length > at + 3 && !/\s/.test(value)
+  }
+  return true
+}
+
+/**
+ * The checks on one text value — a field's own, or one language of a localized one —
+ * as the backend makes them: `max_length` in characters, then the `format`. `at` names
+ * the value: the field, or `field.lang`.
+ */
+function checkText(field, value, at) {
+  if (typeof value !== 'string') return { field: at, rule: 'type', detail: `item.data.${at} must be a string` }
+  if (Number.isInteger(field.max_length) && charCount(value) > field.max_length) {
+    return {
+      field: at,
+      rule: 'max_length',
+      detail: `item.data.${at} exceeds max_length=${field.max_length}`,
+      params: { max_length: field.max_length },
+    }
+  }
+  if (typeof field.format === 'string' && value !== '' && !matchesFormat(value, field.format)) {
+    return {
+      field: at,
+      rule: 'format',
+      detail: `item.data.${at} = ${JSON.stringify(value)} is not a valid ${field.format}`,
+      params: { format: field.format },
+    }
+  }
+  return null
+}
+
 /**
- * Check a record against a lowered `fields` map. Returns a list of violations.
+ * Check a record against a lowered `fields` map. Returns a list of violations, each
+ * `{ field, rule, detail, params? }` — `rule` named as the backend names it, `params` the
+ * declaration's bound it carries beside it (`max_length`, `min`, `max`, `format`).
  *
  * ⛔ **A key the schema does not declare is NOT a violation.** We have no evidence
  * that the real store rejects extras, and inventing that rule here would refuse
@@ -239,16 +325,32 @@ export function checkFields(fields, data, path = '') {
   const record = data && typeof data === 'object' ? data : {}
 
   for (const [name, field] of Object.entries(fields)) {
+    // A nested section is a section of its own, with items of its own — not a field.
+    if (field?.type === 'section') continue
     const at = path ? `${path}.${name}` : name
     const value = record[name]
     const missing = value === undefined || value === null
 
     if (field.required && missing) {
-      problems.push({ field: at, rule: 'required', detail: `'${at}' is required` })
+      problems.push({ field: at, rule: 'required', detail: `item.data.${at} is required` })
       continue
     }
     if (missing) continue
 
+    // ⭐ A localized text field holds a string — its value in every language — or a
+    // per-language object, each language's value checked as the field's text is
+    // (MEASURED 2026-10-14). `@` is the object's metadata, not a language.
+    if (field.localized === true && TEXT_TYPES.has(field.type) && field.multiple !== true) {
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const found = Object.entries(value)
+          .filter(([lang]) => lang !== '@')
+          .map(([lang, v]) => checkText(field, v, `${at}.${lang}`))
+          .find(Boolean)
+        if (found) problems.push(found)
+        continue
+      }
+    }
+
     // A list, in either spelling. The VALUE must be an array; each entry is then
     // checked against the element shape, indexed the way `uniweb validate` names it
     // (`outcomes[1]`), so one vocabulary covers both lanes.
@@ -260,14 +362,28 @@ export function checkFields(fields, data, path = '') {
       }
       value.forEach((entry, i) => {
         const entryAt = `${at}[${i}]`
+        // A localized list's entry is a string or a per-language object, as a single value is.
+        if (field.localized === true && TEXT_TYPES.has(element.type) && entry && typeof entry === 'object' && !Array.isArray(entry)) {
+          const found = Object.entries(entry)
+            .filter(([lang]) => lang !== '@')
+            .map(([lang, v]) => checkText(field, v, `${entryAt}.${lang}`))
+            .find(Boolean)
+          if (found) problems.push(found)
+          return
+        }
         if (satisfiesType(element.type, entry) === false) {
           problems.push({
             field: entryAt,
             rule: 'type',
-            detail: `'${entryAt}' expects ${element.type}, got ${Array.isArray(entry) ? 'array' : typeof entry}`,
+            detail: `item.data.${entryAt} expects ${element.type}, got ${Array.isArray(entry) ? 'array' : typeof entry}`,
           })
           return
         }
+        const bounded = boundOf({ ...field, type: element.type }, entry, entryAt)
+        if (bounded) {
+          problems.push(bounded)
+          return
+        }
         if (element.fields) problems.push(...checkFields(element.fields, entry, entryAt))
       })
       continue
@@ -277,13 +393,20 @@ export function checkFields(fields, data, path = '') {
       problems.push({
         field: at,
         rule: 'type',
-        detail: `'${at}' expects ${field.type}, got ${Array.isArray(value) ? 'array' : typeof value}`,
+        detail: `item.data.${at} expects ${field.type}, got ${Array.isArray(value) ? 'array' : typeof value}`,
       })
       continue
     }
 
+    const bounded = boundOf(field, value, at)
+    if (bounded) {
+      problems.push(bounded)
+      continue
+    }
+
+    // An `enum` is the backend's `one_of` rule — refused under that name.
     if (Array.isArray(field.enum) && field.enum.length && !field.enum.includes(value)) {
-      problems.push({ field: at, rule: 'enum', detail: `'${at}' must be one of ${field.enum.join(', ')}` })
+      problems.push({ field: at, rule: 'one_of', detail: `item.${at} = ${JSON.stringify(value)} is not one of the allowed values` })
       continue
     }
 
@@ -292,6 +415,28 @@ export function checkFields(fields, data, path = '') {
   return problems
 }
 
+/**
+ * The bound a value of a field's type breaks, as the backend checks it — `max_length`
+ * on text, `min` and `max` on a number, a `date`'s precision — or null.
+ * (MEASURED 2026-10-14, each with the bound beside the rule.)
+ */
+function boundOf(field, value, at) {
+  if (TEXT_TYPES.has(field.type) && typeof value === 'string') return checkText(field, value, at)
+  if (typeof value === 'number' && ['int', 'integer', 'decimal', 'number'].includes(field.type)) {
+    if (typeof field.min === 'number' && value < field.min) {
+      return { field: at, rule: 'min', detail: `item.data.${at}=${value} below min=${field.min}`, params: { min: field.min } }
+    }
+    if (typeof field.max === 'number' && value > field.max) {
+      return { field: at, rule: 'max', detail: `item.data.${at}=${value} above max=${field.max}`, params: { max: field.max } }
+    }
+  }
+  if (field.type === 'date' && typeof value === 'string' && !isDateAt(value, field.format)) {
+    const shape = ['year-month', 'year'].includes(field.format) ? field.format : 'date'
+    return { field: at, rule: 'format', detail: `item.data.${at} is not a valid ${shape} (\`${value}\`)`, params: { format: shape } }
+  }
+  return null
+}
+
 /** Keys present in the write that the section does not declare. Diagnostic only — see checkFields. */
 function undeclaredKeys(fields, data) {
   if (!fields || !data || typeof data !== 'object') return []