@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/elements/define.ts

@@ -0,0 +1,195 @@
+import { z, type ZodType } from 'zod'
+import type { ContainerId, ElementId } from './ids'
+
+export type Mode = 'draft' | 'publish'
+export type Severity = 'error' | 'warning'
+export type Id = string | number
+/** A media, page or entry id as stored: a positive integer or a non-empty string. */
+export const Id: ZodType<Id> = z.union([z.int().positive(), z.string().trim().min(1)])
+
+/**
+ * An absolute http(s) URL, or a root-relative path. The character after the leading `/` may be
+ * neither `/` nor `\`: a browser reads `//host` and `/\host` alike as another host. Text and Link
+ * share it.
+ */
+export const URL_RE = /^(https?:\/\/\S+|\/(?:[^\/\\\s]\S*)?)$/
+/** A phone number: an optional leading `+`, a digit, then at least five more digits, spaces, parentheses or hyphens. */
+export const TEL_RE = /^\+?[0-9][0-9 ()\-]{5,}$/
+
+/** An issue relative to one leaf value; the walker prefixes the leaf's path. */
+export type LeafIssue = { path: (string | number)[]; code: string; message: string; severity?: Severity }
+/** An issue at a full path such as `page:4f2/blocks/b1/photo/alt`. */
+export type Issue = { path: string; code: string; message: string; severity: Severity }
+
+export type Ref =
+  | { kind: 'media'; id: Id }
+  | { kind: 'page'; id: Id }
+  | { kind: 'entry'; collection: string; id: Id; depth: number }
+  | { kind: 'single'; key: string }
+  | { kind: 'query'; collection: string; query: unknown }
+  | { kind: 'inverse'; collection: string; field: string; id: Id }
+
+export type ImageCrop = { x: number; y: number; width: number; height: number }
+export type Rendition = {
+  crop: ImageCrop | null
+  url: string
+  width: number | null
+  height: number | null
+  blurDataURL?: string
+  status: 'ready' | 'processing' | 'error'
+}
+export type MediaRecord = {
+  id: Id
+  url: string
+  mimeType: string
+  width: number | null
+  height: number | null
+  filename: string
+  blurDataURL?: string
+  /** Renditions the platform has produced for this asset, one per crop. Absent means none yet. */
+  renditions?: Rendition[]
+}
+/** A media record as a read value carries it: everything but the platform's renditions. Image, Video and File share it. */
+export type MediaAsset = Omit<MediaRecord, 'renditions'>
+export const MediaAssetSchema = z.object({ id: Id, url: z.string(), mimeType: z.string(), width: z.number().nullable(), height: z.number().nullable(), filename: z.string(), blurDataURL: z.string().optional() })
+export type PageRecord = { id: Id; route: string; title: string }
+/** A stored entry as the platform hands it to `expand`. */
+export type EntryRecord = { id: Id; slug: string; route?: string; fields: Record<string, unknown>; blocks?: unknown[] }
+export type EntryRead = {
+  id: Id
+  collection: string
+  status: 'ready' | 'missing'
+  slug?: string
+  route?: string
+  /** Present when expanded to depth ≥ 1. */
+  fields?: Record<string, unknown>
+}
+/** Read schema of an entry reached through a relation, selection or query. */
+export const EntryReadSchema = z.object({ id: Id, collection: z.string(), status: z.enum(['ready', 'missing']), slug: z.string().optional(), route: z.string().optional(), fields: z.record(z.string(), z.unknown()).optional() })
+
+/** Everything `expand` may ask for. Built by `ops/expand` from pre-fetched data; the leaf never fetches. */
+export type ExpandCtx = {
+  at: string
+  draft: boolean
+  /** Draft only: the overlay keys (`overlayKey(at)`) of this document's leaves that read in another language than the one asked for. */
+  fallbacks?: ReadonlySet<string>
+  /** The language a translated frame reads in, read from a draft request's `DRAFT_LOCALE_PARAM`, which internal link hrefs keep as that parameter. */
+  draftLocale?: string
+  media(id: Id): MediaRecord | undefined
+  page(id: Id): PageRecord | undefined
+  /** The Single's read value, already expanded by the caller. */
+  single(key: string): unknown
+  entry(collection: string, id: Id, depth: number): EntryRead
+  query(collection: string, query: unknown): { entries: EntryRead[]; total: number }
+  inverse(collection: string, field: string, id: Id): EntryRead[]
+}
+export type SeedCtx = {
+  importAsset(source: string): Promise<Id>
+  resolvePage(key: string): Id
+  resolveEntry(collection: string, key: string): Id
+  newId(): string
+}
+/** `hasDefault` is true only when the value is absent and a declared default reads in its place. */
+export type FieldMeta = { required: boolean; hasDefault: boolean }
+
+export type LeafDecl = {
+  element: ElementId
+  /** When `false`, the field is never translated. */
+  translatable?: boolean
+  label?: string
+  description?: string
+  required?: boolean
+  /** Seed shape. */
+  default?: unknown
+  /** Sub-paths a client may not change, e.g. `['to']` on a link. */
+  lock?: string[]
+  renamedFrom?: string
+  options?: Record<string, unknown>
+}
+export type GroupDecl = { container: 'u90/group'; label?: string; fields: Record<string, FieldDecl>; order?: string[] }
+export type ListDecl = { container: 'u90/list'; label?: string; item: FieldDecl; min?: number; max?: number; default?: unknown[] }
+export type ZoneDecl = { container: 'u90/zone'; label?: string; allow: string[]; default?: string[]; fixed?: boolean }
+export type FieldDecl = LeafDecl | GroupDecl | ListDecl | ZoneDecl
+export const isLeaf = (d: FieldDecl): d is LeafDecl => 'element' in d
+
+export type BlockDecl = { name: string; label: string; fields: Record<string, FieldDecl>; entry?: string; order?: string[] }
+export type CollectionDecl = {
+  name: string
+  label: string
+  fields: Record<string, FieldDecl>
+  template?: ZoneDecl
+  defaultSort?: { field: string; dir: 'asc' | 'desc' } | 'manual'
+  order?: string[]
+}
+export type SingleDecl = { key: string; field: FieldDecl }
+export type Schema = {
+  blocks: Record<string, BlockDecl>
+  collections: Record<string, CollectionDecl>
+  singles: Record<string, SingleDecl>
+}
+export type DocumentDecl =
+  | { kind: 'page'; blocks: ZoneDecl }
+  | { kind: 'layout'; blocks: ZoneDecl }
+  | { kind: 'entry'; collection: string }
+  | { kind: 'single'; key: string }
+
+export const SLOT = 'SLOT'
+
+/**
+ * What a language overlay holds for this leaf, and how it lands on the stored value. Destinations,
+ * media and structure never travel in an overlay: a link's overlay is its label, an image's its alt
+ * text and caption. `apply` answers undefined when there is no base value to translate.
+ */
+export type TranslationCodec<O, V, T> = {
+  applies(o: O): boolean
+  value(o: O): ZodType<T>
+  pick(v: V, o: O): T | null
+  apply(base: V | undefined, t: T, o: O): V | undefined
+  /** Whether a stored value has a part an overlay could land on, such as a video's poster. Absent, every stored value has. */
+  present?(v: V, o: O): boolean
+}
+
+export type ElementEntry<O = any, S = unknown, V = unknown, R = unknown> = {
+  id: ElementId
+  version: number
+  label: string
+  placement: 'any' | 'collection' | 'content'
+  options: ZodType<O>
+  seed(o: O): ZodType<S>
+  stored(o: O): ZodType<V>
+  /**
+   * The lenient shape a stored value must have to be read; defaults to `stored(o)`. An element whose
+   * options narrow `stored` into an enum, a union or an integer declares one without those rules, so
+   * content written under wider options keeps reading while `validate` reports it.
+   */
+  shape?(o: O): ZodType
+  read(o: O): ZodType<R>
+  /** Publish-only completeness. `v` is undefined when the field is absent from storage. */
+  complete(v: V | undefined, o: O, field: FieldMeta): LeafIssue[]
+  refs(v: V, o: O, at: string): Ref[]
+  toStored(seed: S, o: O, ctx: SeedCtx): Promise<V>
+  expand(v: V, o: O, ctx: ExpandCtx): R
+  /** Read shape of a seed value, for defaults of fields absent from storage. */
+  expandSeed(seed: S, o: O, ctx: ExpandCtx): R
+  toText(v: V, o: O): string
+  translatable(v: V, o: O): { path: (string | number)[]; value: string }[]
+  /** What a language overlay holds for this element; null where nothing translates. */
+  translation: TranslationCodec<O, V, any> | null
+  empty(o: O): V
+  upgrade: Record<number, (old: unknown) => unknown>
+}
+export const defineElement = <O, S, V, R>(e: ElementEntry<O, S, V, R>) => e
+
+export type Child = { key: string; decl: FieldDecl; value: unknown; set(v: unknown): void }
+export type ContainerEntry<D extends FieldDecl = FieldDecl> = {
+  id: ContainerId
+  children(decl: D, value: unknown, schema: Schema): Child[]
+  /** Structural checks on the container's own value; the walker prefixes the path. */
+  enter(decl: D, value: unknown, schema: Schema): LeafIssue[]
+}
+export const defineContainer = <D extends FieldDecl>(c: ContainerEntry<D>) => c
+
+export const requiredIssue = (present: boolean, field: FieldMeta): LeafIssue[] =>
+  !present && field.required && !field.hasDefault
+    ? [{ path: [], code: 'required', message: 'A value is required to publish.' }]
+    : []

package/src/elements/ids.ts

@@ -0,0 +1,50 @@
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+const DIGITS = '0123456789'
+
+/**
+ * `n` characters from `alphabet`, unbiased: a byte at or above the largest multiple of the alphabet's length below 256
+ * is redrawn, so every symbol is equally likely. Web Crypto, so the same code runs in Node, browsers and edge runtimes. */
+const draw = (n: number, alphabet: string): string => {
+  const limit = 256 - (256 % alphabet.length)
+  let out = ''
+  while (out.length < n) {
+    for (const byte of globalThis.crypto.getRandomValues(new Uint8Array(n * 2))) {
+      if (byte >= limit) continue
+      out += alphabet[byte % alphabet.length]
+      if (out.length === n) break
+    }
+  }
+  return out
+}
+
+/** A stored `_id`: a list item or a block. 1 to 16 lower-case letters and digits, so ids stored before the 12-character rule still read. */
+export const ID_RE = /^[a-z0-9]{1,16}$/
+/** 12 random characters (about 62 bits): an `_id`, minted by the platform. */
+export const newId = (): string => draw(12, ALPHABET)
+
+/**
+ * A page's, an entry's, a layout's, a Single's or a code draft's id: 16 characters that start with a digit and hold a
+ * letter. A declared key starts with a letter, so the two never look alike; and an id is never all digits, so nothing
+ * that reads a numeric string as a number can turn one into a number.
+ */
+export const DOCUMENT_ID_RE = /^(?=.*[a-z])[0-9][a-z0-9]{15}$/
+export const isDocumentId = (value: unknown): value is string => typeof value === 'string' && DOCUMENT_ID_RE.test(value)
+export const newDocumentId = (): string => {
+  for (;;) {
+    const id = draw(1, DIGITS) + draw(15, ALPHABET)
+    if (DOCUMENT_ID_RE.test(id)) return id
+  }
+}
+
+export const ELEMENT_IDS = [
+  'u90/text', 'u90/rich-text', 'u90/image', 'u90/video', 'u90/file', 'u90/link',
+  'u90/date', 'u90/number', 'u90/boolean', 'u90/choice',
+  'u90/relation', 'u90/selection', 'u90/query', 'u90/single',
+] as const
+export type ElementId = (typeof ELEMENT_IDS)[number]
+
+export const CONTAINER_IDS = ['u90/group', 'u90/list', 'u90/zone'] as const
+export type ContainerId = (typeof CONTAINER_IDS)[number]
+
+/** `u90/rich-text` → `rich-text`; used for fixture folders and docs anchors. */
+export const shortId = (id: ElementId | ContainerId) => id.slice('u90/'.length)

package/src/elements/index.ts

@@ -0,0 +1,35 @@
+export const MODULE = '@unitninety/site-kit/elements'
+export * from './ids'
+export * from './define'
+export { path, newId, ID_RE, type Path, type DocKind } from './path'
+export { orderedKeys, orderedEntries } from './order'
+export * from './tokens'
+export { validateLeaf, expandLeaf, parseOptions, zodIssues, hasStoredShape } from './leaf'
+export { text, TextOptions, type TextRead, type TextSegment } from './leaves/text'
+export { boolean, BooleanOptions, type BooleanRead } from './leaves/boolean'
+export { number, NumberOptions, type NumberRead } from './leaves/number'
+export { date, DateOptions, type DateRead } from './leaves/date'
+export { choice, ChoiceOptions, type ChoiceRead, type ChoiceReadValue } from './leaves/choice'
+export { link, LinkOptions, LinkTo, linkKind, hrefOf, DRAFT_LOCALE_PARAM, type LinkRead, type LinkKind } from './leaves/link'
+export { single, SingleOptions } from './leaves/single'
+export { richText, RichTextOptions, richTextToPlain, type RichTextRead } from './leaves/rich-text'
+export { image, ImageOptions, ImageConstraints, imageStored, imageSeed, expandImage, imageToStored, type ImageRead, type ImageStored, type ImageSeed, type ImageReadVariant, type ImageAsset } from './leaves/image'
+export { video, VideoOptions, mediaAssetRead, type VideoRead, type MediaAssetRead } from './leaves/video'
+export { file, FileOptions, type FileRead } from './leaves/file'
+export { relation, RelationOptions, isDerived, EntryRef, resolveEntryRef } from './leaves/relation'
+export { selection, SelectionOptions, type EntriesRead } from './leaves/selection'
+export { query, QueryOptions, QueryStored, applyQueryPicks, FILTERABLE, SORTABLE } from './leaves/query'
+export { elements, getElement, CONTRACTS, CURRENT_CONTRACT } from './registry'
+export { validateSchema, FieldDeclSchema, BlockDeclSchema, CollectionDeclSchema, SingleDeclSchema, SchemaSchema } from './declaration'
+export { containers, getContainer } from './registry'
+export { walk, walkDocument, type Visitor, type LeafNode, type ContainerNode } from './walk'
+export { validate, type ValidateOptions } from './ops/validate'
+export { collectRefs } from './ops/refs'
+export { expand, expandField, makeCtx, entryKey, queryKey, inverseKey, type Resolved } from './ops/expand'
+export { prefixedRoute } from './prefix'
+export { seed, seedItem, seedIssues, SeedError, type SeedKnown } from './ops/seed'
+export { textOf } from './ops/text'
+export { translatableParts } from './ops/translatable'
+export { overlayKey, translatableLeaves, applyOverlay, type OverlayValues } from './ops/overlay'
+export { upgrade, UpgradeError, type UpgradeOptions } from './ops/upgrade'
+export { toJSONSchema } from './jsonSchema'

package/src/elements/jsonSchema.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+import { isLeaf, type FieldDecl, type Schema } from './define'
+import { orderedEntries } from './order'
+import { ID_RE } from './path'
+import { getElement } from './registry'
+
+type JsonSchema = Record<string, unknown>
+const id = { type: 'string', pattern: ID_RE.source }
+
+/** JSON Schema (draft 2020-12) of a declaration's STORED shape. Used for agent tool schemas and docs. */
+export function toJSONSchema(decl: FieldDecl, schema?: Schema): JsonSchema {
+  if (isLeaf(decl)) {
+    const entry = getElement(decl.element)
+    const { $schema: _s, ...rest } = z.toJSONSchema(entry.stored(entry.options.parse(decl.options ?? {}))) as JsonSchema
+    return { ...rest, ...(decl.label ? { title: decl.label } : {}), ...(decl.description ? { description: decl.description } : {}) }
+  }
+  if (decl.container === 'u90/group')
+    return { type: 'object', properties: Object.fromEntries(orderedEntries(decl.fields, decl.order).map(([n, f]) => [n, toJSONSchema(f, schema)])), additionalProperties: false }
+  if (decl.container === 'u90/list') {
+    // validateSchema rejects a list item that isn't an element or a group, so only those two shapes reach here.
+    let item: JsonSchema
+    if (isLeaf(decl.item)) {
+      item = { type: 'object', properties: { _id: id, _value: toJSONSchema(decl.item, schema) }, required: ['_id', '_value'], additionalProperties: false }
+    } else {
+      const inner = toJSONSchema(decl.item, schema)
+      item = { type: 'object', properties: { _id: id, ...(inner.properties as object) }, required: ['_id'], additionalProperties: false }
+    }
+    return { type: 'array', items: item, ...(decl.min !== undefined ? { minItems: decl.min } : {}), ...(decl.max !== undefined ? { maxItems: decl.max } : {}) }
+  }
+  const blocks = decl.allow.map((name) => {
+    const block = schema?.blocks[name]
+    const fields = block ? (toJSONSchema({ container: 'u90/group', fields: block.fields, order: block.order }, schema).properties as object) : {}
+    return { type: 'object', properties: { _id: id, _block: { const: name }, ...fields }, required: ['_id', '_block'], additionalProperties: false }
+  })
+  return { type: 'array', items: { oneOf: blocks } }
+}

package/src/elements/leaf.ts

@@ -0,0 +1,98 @@
+import type { ZodError } from 'zod'
+import { overlayKey } from './path'
+import type { ElementEntry, ExpandCtx, FieldMeta, LeafDecl, LeafIssue, Mode } from './define'
+
+/** zod issues → LeafIssue. A `params.code` set by an element's own check wins over zod's generic code. */
+export const zodIssues = (error: ZodError): LeafIssue[] =>
+  error.issues.map((i) => ({
+    path: i.path as (string | number)[],
+    code: (i as { params?: { code?: string } }).params?.code ?? i.code,
+    message: i.message,
+  }))
+
+export function parseOptions(entry: ElementEntry, decl: LeafDecl) {
+  const r = entry.options.safeParse(decl.options ?? {})
+  return r.success
+    ? ({ ok: true, options: r.data } as const)
+    : ({ ok: false, issues: zodIssues(r.error).map((i) => ({ ...i, path: ['options', ...i.path] })) } as const)
+}
+
+/**
+ * zod codes meaning a value does not have its element's stored shape; any other failure (a length,
+ * a pattern, a step, a custom rule) leaves the shape intact, so the value can still be read. The
+ * check parses with the element's `shape` where it declares one, else with `stored`, and a failure
+ * with one of these codes counts whichever raised it, an element's own refinement included (a
+ * query's value-shape rules raise `invalid_type`). Under `stored`, an option that becomes an enum,
+ * a union or an integer rule would turn narrowing it into a shape failure and blank old content, so
+ * rich text, number and choice declare a `shape` without those rules: their content written before
+ * a declaration narrowed keeps rendering while `validate` reports it. `invalid_format` is a shape
+ * code too: a value whose format *is* its type (an ISO date, a link's `url`/`email`/`tel`
+ * destination) has no usable shape once the format fails. Text's own format rules (`format: 'email'`
+ * etc.) are checked as custom issues, not `invalid_format`, so a bad-format text still reads.
+ */
+const SHAPE_CODES = new Set(['invalid_type', 'invalid_union', 'invalid_value', 'invalid_key', 'invalid_element', 'unrecognized_keys', 'invalid_format'])
+/**
+ * Whether `value` has the stored shape its element's operations assume. `refs`, `expand`, `toText`
+ * and `translatable` only ever see a value that passes, so a malformed stored value is reported by
+ * `validate`, reads as the element's empty value, and never throws inside an operation.
+ */
+export const hasStoredShape = (entry: ElementEntry, options: unknown, value: unknown): boolean => {
+  const r = (entry.shape ? entry.shape(options) : entry.stored(options)).safeParse(value)
+  return r.success || r.error.issues.every((i) => !SHAPE_CODES.has(i.code))
+}
+
+/**
+ * A default stands in only for an absent value (an explicit `null` stays `null`), so only then can it
+ * satisfy `required`, and only when the default is itself complete. A blank default (`''`, a rich text
+ * with no words, a link with no label) satisfies nothing, so a required field declared with one still
+ * asks for a value before publishing.
+ */
+const completeDefault = (entry: ElementEntry, options: unknown, value: unknown): boolean => {
+  if (value === undefined || value === null) return false
+  const r = entry.stored(options).safeParse(value)
+  if (r.success) return entry.complete(r.data, options, { required: true, hasDefault: false }).length === 0
+  // A seed shape the stored schema does not take (an image's `{ source }`, an entry `$ref`): only a blank string or list is blank.
+  return !(typeof value === 'string' && value.trim() === '') && !(Array.isArray(value) && value.length === 0)
+}
+const meta = (entry: ElementEntry, decl: LeafDecl, options: unknown, absent: boolean): FieldMeta => ({
+  required: decl.required === true,
+  hasDefault: absent && decl.default !== undefined && completeDefault(entry, options, decl.default),
+})
+
+/**
+ * Strict type check in every mode; `complete` only when publishing.
+ * `undefined` means the field is absent from storage (it reads as its default), so only completeness applies.
+ */
+export function validateLeaf(entry: ElementEntry, decl: LeafDecl, value: unknown, mode: Mode): LeafIssue[] {
+  const o = parseOptions(entry, decl)
+  if (!o.ok) return o.issues
+  if (value === undefined) return mode === 'publish' ? entry.complete(undefined, o.options, meta(entry, decl, o.options, true)) : []
+  const r = entry.stored(o.options).safeParse(value)
+  if (!r.success) return zodIssues(r.error)
+  return mode === 'publish' ? entry.complete(r.data, o.options, meta(entry, decl, o.options, false)) : []
+}
+
+/**
+ * Read shape of a stored value. An absent value (`undefined`) reads as the declared default or `empty`.
+ * A stored `null` is handed to the element's `expand`, which decides what it means: nullable elements
+ * return `null`, and `u90/single` / the derived side of `u90/relation` resolve it. A value without the
+ * stored shape, or a declaration whose options or default do not parse, reads as the empty value.
+ */
+export function expandLeaf(entry: ElementEntry, decl: LeafDecl, value: unknown, ctx: ExpandCtx): unknown {
+  const read = expandLeafValue(entry, decl, value, ctx)
+  // In draft, a leaf the reply lists as a fallback is marked beside its `$path`; a published read never is.
+  if (ctx.draft && ctx.fallbacks?.size && read && typeof read === 'object' && typeof (read as { $path?: unknown }).$path === 'string' && ctx.fallbacks.has(overlayKey(ctx.at))) return { ...read, $fallback: true }
+  return read
+}
+function expandLeafValue(entry: ElementEntry, decl: LeafDecl, value: unknown, ctx: ExpandCtx): unknown {
+  const parsed = entry.options.safeParse(decl.options ?? {})
+  if (!parsed.success) return null
+  const o = parsed.data
+  if (value === undefined) {
+    if (decl.default === undefined) return entry.expand(entry.empty(o), o, ctx)
+    const seeded = entry.seed(o).safeParse(decl.default)
+    return seeded.success ? entry.expandSeed(seeded.data, o, ctx) : entry.expand(entry.empty(o), o, ctx)
+  }
+  if (value !== null && !hasStoredShape(entry, o, value)) return entry.expand(entry.empty(o), o, ctx)
+  return entry.expand(value, o, ctx)
+}

package/src/elements/leaves/boolean.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+import { defineElement, type ExpandCtx } from '../define'
+
+export const BooleanOptions = z.strictObject({})
+/** How a boolean reads: its value, and `$path` in draft, so the Canvas can select it (R34). */
+export type BooleanRead = { value: boolean; $path?: string }
+const schema = z.boolean()
+const read = z.object({ value: z.boolean(), $path: z.string().optional() })
+const expand = (v: boolean, _o: unknown, ctx: ExpandCtx): BooleanRead => ({ value: v === true, ...(ctx.draft ? { $path: ctx.at } : {}) })
+
+export const boolean = defineElement({
+  id: 'u90/boolean',
+  version: 1,
+  label: 'Boolean',
+  placement: 'any',
+  options: BooleanOptions,
+  seed: () => schema,
+  stored: () => schema,
+  read: () => read,
+  complete: () => [],
+  refs: () => [],
+  toStored: async (seed) => seed,
+  expand,
+  expandSeed: expand,
+  toText: () => '',
+  translatable: () => [],
+  translation: null,
+  empty: () => false,
+  upgrade: {},
+})

package/src/elements/leaves/choice.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod'
+import { defineElement, requiredIssue } from '../define'
+
+export const ChoiceOptions = z.strictObject({
+  values: z.array(z.strictObject({ value: z.string().min(1), label: z.string().min(1) })).min(1),
+  multiple: z.boolean().default(false),
+})
+type O = z.infer<typeof ChoiceOptions>
+/** One chosen value as it reads. */
+export type ChoiceRead = { value: string; label: string; $path?: string }
+/** What a choice field reads as: one item, a list of them when `multiple`, or `null` when cleared. */
+export type ChoiceReadValue = ChoiceRead | ChoiceRead[] | null
+
+const one = (o: O) => z.enum(o.values.map((v) => v.value) as [string, ...string[]])
+const stored = (o: O) =>
+  o.multiple
+    ? z.array(one(o)).superRefine((vs, ctx) => {
+        if (new Set(vs).size !== vs.length)
+          ctx.addIssue({ code: 'custom', message: 'Each value may be chosen once.', params: { code: 'duplicate' } })
+      })
+    : one(o).nullable()
+/** Any string, or a list of them: a value no longer among `values` still reads, labelled by itself. */
+const shape = (o: O) => (o.multiple ? z.array(z.string()) : z.string().nullable())
+const readOne = z.object({ value: z.string(), label: z.string(), $path: z.string().optional() })
+const read = (o: O) => (o.multiple ? z.array(readOne) : readOne.nullable())
+const label = (o: O, v: string) => o.values.find((x) => x.value === v)?.label ?? v
+const expand = (v: string | string[] | null, o: O, ctx: { at: string; draft: boolean }): ChoiceReadValue => {
+  const tag = ctx.draft ? { $path: ctx.at } : {}
+  if (Array.isArray(v)) return v.map((x) => ({ value: x, label: label(o, x), ...tag }))
+  return v === null ? null : { value: v, label: label(o, v), ...tag }
+}
+
+export const choice = defineElement({
+  id: 'u90/choice',
+  version: 1,
+  label: 'Choice',
+  placement: 'any',
+  options: ChoiceOptions,
+  seed: stored,
+  stored,
+  shape,
+  read,
+  complete: (v, _o, field) => requiredIssue(Array.isArray(v) ? v.length > 0 : typeof v === 'string', field),
+  refs: () => [],
+  toStored: async (seed) => seed,
+  expand,
+  expandSeed: expand,
+  toText: (v, o) => (Array.isArray(v) ? v.map((x) => label(o, x)).join(', ') : v === null ? '' : label(o, v)),
+  translatable: () => [],
+  translation: null,
+  empty: (o) => (o.multiple ? [] : null),
+  upgrade: {},
+})

package/src/elements/leaves/date.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod'
+import { defineElement, requiredIssue } from '../define'
+
+export const DateOptions = z.strictObject({ min: z.iso.date().optional(), max: z.iso.date().optional() })
+type O = z.infer<typeof DateOptions>
+export type DateRead = { iso: string; $path?: string } | null
+
+const stored = (o: O) =>
+  z.iso
+    .date()
+    .superRefine((v, ctx) => {
+      if ((o.min && v < o.min) || (o.max && v > o.max))
+        ctx.addIssue({ code: 'custom', message: `Must be between ${o.min ?? 'any'} and ${o.max ?? 'any'}.`, params: { code: 'range' } })
+    })
+    .nullable()
+const read = z.object({ iso: z.iso.date(), $path: z.string().optional() }).nullable()
+const expand = (v: string | null, _o: O, ctx: { at: string; draft: boolean }): DateRead =>
+  v === null ? null : { iso: v, ...(ctx.draft ? { $path: ctx.at } : {}) }
+
+export const date = defineElement({
+  id: 'u90/date',
+  version: 1,
+  label: 'Date',
+  placement: 'any',
+  options: DateOptions,
+  seed: stored,
+  stored,
+  read: () => read,
+  complete: (v, _o, field) => requiredIssue(typeof v === 'string', field),
+  refs: () => [],
+  toStored: async (seed) => seed,
+  expand,
+  expandSeed: expand,
+  toText: (v) => v ?? '',
+  translatable: () => [],
+  translation: null,
+  empty: () => null,
+  upgrade: {},
+})

package/src/elements/leaves/file.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod'
+import { Id, MediaAssetSchema, defineElement, requiredIssue, type ExpandCtx, type SeedCtx } from '../define'
+import { mediaAssetRead, type MediaAssetRead } from './video'
+
+export const FileOptions = z.strictObject({
+  mimeTypes: z.array(z.string().regex(/^[a-z]+\/[a-z0-9.+-]+$/i)).min(1).optional(),
+  maxBytes: z.int().positive().optional(),
+})
+type O = z.infer<typeof FileOptions>
+const stored = () => z.strictObject({ asset: Id, label: z.string(), description: z.string().nullable(), downloadName: z.string().nullable() }).nullable()
+type Stored = z.infer<ReturnType<typeof stored>>
+const seed = () =>
+  z.strictObject({ asset: z.union([Id, z.strictObject({ source: z.string().trim().min(1) })]), label: z.string().default(''), description: z.string().nullable().default(null), downloadName: z.string().nullable().default(null) }).nullable()
+export type FileRead = { asset: MediaAssetRead | null; status: 'ready' | 'missing'; label: string; description: string | null; downloadName: string | null; $path?: string } | null
+const read = z.object({ asset: MediaAssetSchema.nullable(), status: z.enum(['ready', 'missing']), label: z.string(), description: z.string().nullable(), downloadName: z.string().nullable(), $path: z.string().optional() }).nullable()
+const expand = (v: Stored, _o: O, ctx: ExpandCtx): FileRead =>
+  v === null ? null : { ...mediaAssetRead(ctx.media(v.asset)), label: v.label, description: v.description, downloadName: v.downloadName, ...(ctx.draft ? { $path: ctx.at } : {}) }
+
+export const file = defineElement({
+  id: 'u90/file',
+  version: 1,
+  label: 'File',
+  placement: 'any',
+  options: FileOptions,
+  seed,
+  stored,
+  read: () => read,
+  complete: (v, _o, field) => {
+    if (v == null) return requiredIssue(false, field)
+    return v.label.trim() ? [] : [{ path: ['label'], code: 'blank', message: 'Give the download a label.' }]
+  },
+  refs: (v) => (v ? [{ kind: 'media', id: v.asset }] : []),
+  toStored: async (s, _o, ctx: SeedCtx) => (s === null ? null : { ...s, asset: typeof s.asset === 'object' ? await ctx.importAsset(s.asset.source) : s.asset }),
+  expand,
+  expandSeed: (s, o, ctx) => {
+    if (s === null) return null
+    if (typeof s.asset !== 'object') return expand({ ...s, asset: s.asset }, o, ctx)
+    const src = s.asset.source
+    return { asset: { id: src, url: src, mimeType: '', width: null, height: null, filename: src.split('/').pop() ?? src }, status: 'ready', label: s.label, description: s.description, downloadName: s.downloadName, ...(ctx.draft ? { $path: ctx.at } : {}) }
+  },
+  toText: (v) => (v ? [v.label, v.description ?? ''].filter(Boolean).join(' ') : ''),
+  translatable: (v) => (v ? [...(v.label ? [{ path: ['label'], value: v.label }] : []), ...(v.description ? [{ path: ['description'], value: v.description }] : [])] : []),
+  translation: {
+    applies: () => true,
+    value: () => z.object({ label: z.string().optional(), description: z.string().optional() }).refine((t) => t.label !== undefined || t.description !== undefined, 'A file translation names its label or description.'),
+    pick: (v) => {
+      if (!v) return null
+      const label = v.label ? v.label : undefined
+      const description = v.description ? v.description : undefined
+      return label === undefined && description === undefined ? null : { ...(label !== undefined ? { label } : {}), ...(description !== undefined ? { description } : {}) }
+    },
+    apply: (base, t) => (base ? { ...base, ...(t.label !== undefined ? { label: t.label } : {}), ...(t.description !== undefined ? { description: t.description } : {}) } : undefined),
+  },
+  empty: () => null,
+  upgrade: {},
+})