@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/elements/leaves/link.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod'
+import { Id, TEL_RE, URL_RE, defineElement, requiredIssue, type ExpandCtx, type SeedCtx } from '../define'
+import { isDocumentId } from '../ids'
+
+const ANCHOR = z.string().regex(/^[A-Za-z][\w-]*$/)
+const KINDS = ['page', 'entry', 'url', 'email', 'tel'] as const
+export type LinkKind = (typeof KINDS)[number]
+
+export const LinkTo = z.union([
+  z.strictObject({ page: Id, anchor: ANCHOR.optional() }),
+  z.strictObject({ entry: z.strictObject({ collection: z.string().min(1), id: Id }) }),
+  z.strictObject({ url: z.string().regex(URL_RE, 'Expected an absolute URL or a root-relative path.') }),
+  z.strictObject({ email: z.email() }),
+  z.strictObject({ tel: z.string().regex(TEL_RE, 'Expected a phone number.') }),
+])
+export type LinkTo = z.infer<typeof LinkTo>
+/** Seeds may name pages and entries by key instead of id. */
+const LinkToSeed = z.union([
+  z.strictObject({ page: z.union([Id, z.string().min(1)]), anchor: ANCHOR.optional() }),
+  z.strictObject({ entry: z.strictObject({ collection: z.string().min(1), key: z.string().min(1) }) }),
+  z.strictObject({ entry: z.strictObject({ collection: z.string().min(1), id: Id }) }),
+  z.strictObject({ url: z.string().regex(URL_RE) }),
+  z.strictObject({ email: z.email() }),
+  z.strictObject({ tel: z.string().regex(TEL_RE) }),
+])
+type SeedTo = z.infer<typeof LinkToSeed>
+
+export const LinkOptions = z.strictObject({ allow: z.array(z.enum(KINDS)).min(1).default([...KINDS]) })
+type O = z.infer<typeof LinkOptions>
+export const linkKind = (to: LinkTo): LinkKind => KINDS.find((k) => k in to)!
+
+const stored = (o: O) =>
+  z
+    .strictObject({
+      label: z.string(),
+      to: LinkTo.nullable(),
+      newTab: z.boolean(),
+    })
+    .superRefine((v, ctx) => {
+      if (v.to && !o.allow.includes(linkKind(v.to)))
+        ctx.addIssue({ code: 'custom', path: ['to'], message: `This link may only point at: ${o.allow.join(', ')}.`, params: { code: 'not-allowed' } })
+    })
+    .nullable()
+type Stored = z.infer<ReturnType<typeof stored>>
+const seed = () =>
+  z.strictObject({ label: z.string().default(''), to: LinkToSeed.nullable().default(null), newTab: z.boolean().default(false) }).nullable()
+type SeedValue = z.infer<ReturnType<typeof seed>>
+
+export type LinkRead = { label: string; href: string | null; newTab: boolean; to: LinkTo | null; status: 'ready' | 'missing'; $path?: string } | null
+const read = z
+  .object({ label: z.string(), href: z.string().nullable(), newTab: z.boolean(), to: LinkTo.nullable(), status: z.enum(['ready', 'missing']), $path: z.string().optional() })
+  .nullable()
+
+/**
+ * The site query parameter that carries a language in draft (the Canvas's translated frames). Outside draft a site ignores it.
+ * An internal href keeps it, so following a link inside a translated frame stays in that language.
+ */
+export const DRAFT_LOCALE_PARAM = 'u90-locale'
+/** An href on this site: root-relative, and not `//host`. The same rule as the `Link` component's `isInternal`. */
+const internal = (href: string) => href.startsWith('/') && !href.startsWith('//')
+/** `href` with `DRAFT_LOCALE_PARAM=<locale>` in its query, after any query it already has and before its fragment. A value it already carries is replaced. */
+export const withDraftLocale = (href: string, locale: string): string => {
+  const hashAt = href.indexOf('#')
+  const hash = hashAt < 0 ? '' : href.slice(hashAt)
+  const rest = hashAt < 0 ? href : href.slice(0, hashAt)
+  const queryAt = rest.indexOf('?')
+  const base = queryAt < 0 ? rest : rest.slice(0, queryAt)
+  const pairs = queryAt < 0 ? [] : rest.slice(queryAt + 1).split('&').filter((p) => p !== '' && p.split('=')[0] !== DRAFT_LOCALE_PARAM)
+  return `${base}?${[...pairs, `${DRAFT_LOCALE_PARAM}=${encodeURIComponent(locale)}`].join('&')}${hash}`
+}
+/** In draft with a `draftLocale`, an internal href keeps the language; every other href, and every href outside draft, is unchanged. */
+export const hrefOf = (to: LinkTo | null, ctx: ExpandCtx): { href: string | null; status: 'ready' | 'missing' } => {
+  const r = targetOf(to, ctx)
+  return ctx.draftLocale && r.href && internal(r.href) ? { ...r, href: withDraftLocale(r.href, ctx.draftLocale) } : r
+}
+const targetOf = (to: LinkTo | null, ctx: ExpandCtx): { href: string | null; status: 'ready' | 'missing' } => {
+  if (!to) return { href: null, status: 'ready' }
+  if ('page' in to) {
+    const p = ctx.page(to.page)
+    return p ? { href: `${p.route}${to.anchor ? `#${to.anchor}` : ''}`, status: 'ready' } : { href: null, status: 'missing' }
+  }
+  if ('entry' in to) {
+    const e = ctx.entry(to.entry.collection, to.entry.id, 0)
+    return e.status === 'ready' && e.route ? { href: e.route, status: 'ready' } : { href: null, status: 'missing' }
+  }
+  if ('url' in to) return { href: to.url, status: 'ready' }
+  if ('email' in to) return { href: `mailto:${to.email}`, status: 'ready' }
+  return { href: `tel:${to.tel.replace(/[^+\d]/g, '')}`, status: 'ready' }
+}
+const expand = (v: Stored, _o: O, ctx: ExpandCtx): LinkRead =>
+  v === null ? null : { label: v.label, ...hrefOf(v.to, ctx), newTab: v.newTab, to: v.to, ...(ctx.draft ? { $path: ctx.at } : {}) }
+
+/**
+ * A seed `to` that names a page or an entry by key rather than id. `ExpandCtx` deliberately has no key lookup
+ * (seeding is what resolves keys), so this can never be turned into an href — page and entry keys are treated
+ * the same way here, both unresolvable until `toStored` runs.
+ */
+const isUnresolvedSeedRef = (to: SeedTo | null): boolean =>
+  !!to && (('page' in to && typeof to.page === 'string' && !isDocumentId(to.page)) || ('entry' in to && 'key' in to.entry))
+
+const expandSeed = (s: SeedValue, o: O, ctx: ExpandCtx): LinkRead => {
+  if (s === null) return null
+  if (isUnresolvedSeedRef(s.to)) return { label: s.label, href: null, newTab: s.newTab, to: null, status: 'missing', ...(ctx.draft ? { $path: ctx.at } : {}) }
+  return expand({ label: s.label, to: s.to as LinkTo | null, newTab: s.newTab }, o, ctx)
+}
+
+export const link = defineElement({
+  id: 'u90/link',
+  version: 1,
+  label: 'Link',
+  placement: 'any',
+  options: LinkOptions,
+  seed,
+  stored,
+  read: () => read,
+  complete: (v, _o, field) => {
+    if (v == null) return requiredIssue(false, field)
+    const issues = []
+    if (!v.to && field.required) issues.push({ path: ['to'], code: 'required', message: 'Choose where the link goes.' })
+    if (!v.label.trim()) issues.push({ path: ['label'], code: 'blank', message: 'The link needs words.' })
+    return issues
+  },
+  refs: (v) => {
+    if (!v?.to) return []
+    if ('page' in v.to) return [{ kind: 'page', id: v.to.page }]
+    if ('entry' in v.to) return [{ kind: 'entry', collection: v.to.entry.collection, id: v.to.entry.id, depth: 0 }]
+    return []
+  },
+  toStored: async (s, _o, ctx: SeedCtx) => {
+    if (s === null) return null
+    let to: LinkTo | null = null
+    if (s.to && 'page' in s.to) to = { page: typeof s.to.page === 'string' && !isDocumentId(s.to.page) ? ctx.resolvePage(s.to.page) : s.to.page, ...(s.to.anchor ? { anchor: s.to.anchor } : {}) }
+    else if (s.to && 'entry' in s.to) to = { entry: { collection: s.to.entry.collection, id: 'key' in s.to.entry ? ctx.resolveEntry(s.to.entry.collection, s.to.entry.key) : s.to.entry.id } }
+    else to = s.to
+    return { label: s.label, to, newTab: s.newTab }
+  },
+  expand,
+  expandSeed,
+  toText: (v) => v?.label ?? '',
+  translatable: (v) => (v && v.label ? [{ path: ['label'], value: v.label }] : []),
+  translation: {
+    applies: () => true,
+    value: () => z.object({ label: z.string().min(1) }),
+    pick: (v) => (v?.label ? { label: v.label } : null),
+    apply: (base, t) => (base ? { ...base, label: t.label } : undefined),
+  },
+  empty: () => null,
+  upgrade: {},
+})

package/src/elements/leaves/number.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod'
+import { defineElement, requiredIssue } from '../define'
+
+export const NumberOptions = z.strictObject({
+  integer: z.boolean().default(false),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  step: z.number().positive().optional(),
+})
+type O = z.infer<typeof NumberOptions>
+export type NumberRead = { value: number; $path?: string } | null
+
+const stored = (o: O) => {
+  let s = o.integer ? z.int() : z.number()
+  if (o.min !== undefined) s = s.min(o.min)
+  if (o.max !== undefined) s = s.max(o.max)
+  return s
+    .superRefine((v, ctx) => {
+      if (o.step === undefined) return
+      const offset = (v - (o.min ?? 0)) / o.step
+      if (Math.abs(offset - Math.round(offset)) > 1e-9)
+        ctx.addIssue({ code: 'custom', message: `Must be a multiple of ${o.step}${o.min !== undefined ? ` from ${o.min}` : ''}.`, params: { code: 'step' } })
+    })
+    .nullable()
+}
+/** Any number: `integer`, `min`, `max` and `step` are rules, so a value that breaks one still reads. */
+const SHAPE = z.number().nullable()
+const read = z.object({ value: z.number(), $path: z.string().optional() }).nullable()
+const expand = (v: number | null, _o: O, ctx: { at: string; draft: boolean }): NumberRead =>
+  v === null ? null : { value: v, ...(ctx.draft ? { $path: ctx.at } : {}) }
+
+export const number = defineElement({
+  id: 'u90/number',
+  version: 1,
+  label: 'Number',
+  placement: 'any',
+  options: NumberOptions,
+  seed: stored,
+  stored,
+  shape: () => SHAPE,
+  read: () => read,
+  complete: (v, _o, field) => requiredIssue(typeof v === 'number', field),
+  refs: () => [],
+  toStored: async (seed) => seed,
+  expand,
+  expandSeed: expand,
+  toText: (v) => (v === null ? '' : String(v)),
+  translatable: () => [],
+  translation: null,
+  empty: () => null,
+  upgrade: {},
+})

package/src/elements/leaves/query.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod'
+import { Id, defineElement, type ExpandCtx, type Ref } from '../define'
+import { ELEMENT_IDS, type ElementId } from '../ids'
+import { EntriesReadSchema, type EntriesRead } from './selection'
+
+export const FILTERABLE: readonly ElementId[] = ['u90/choice', 'u90/boolean', 'u90/relation', 'u90/date', 'u90/number']
+export const SORTABLE: readonly ElementId[] = ['u90/text', 'u90/date', 'u90/number']
+const OPS = ['eq', 'neq', 'in', 'not-in', 'is-set'] as const
+
+export const QueryOptions = z.strictObject({
+  to: z.string().min(1),
+  /** field → element of the target collection; filled in by validateSchema from the CollectionDecl. */
+  targetFields: z.record(z.string(), z.enum(ELEMENT_IDS)).optional(),
+})
+type O = z.infer<typeof QueryOptions>
+const Scalar = z.union([z.string(), z.number(), z.boolean()])
+export const QueryStored = z.strictObject({
+  where: z.array(z.strictObject({ field: z.string().min(1), op: z.enum(OPS), value: z.union([Scalar, z.array(Scalar)]).optional() })).optional(),
+  sort: z.union([z.strictObject({ field: z.string().min(1), dir: z.enum(['asc', 'desc']) }), z.literal('manual')]).optional(),
+  limit: z.int().min(1).max(100).optional(),
+  /** Entries the rule returns that this placement leaves out. */
+  exclude: z.array(Id).optional(),
+  /** Entries this placement adds although the rule does not return them. */
+  pin: z.array(Id).optional(),
+  /** A hand-set order: these entries first, in this order, then the rest in the rule's own order. */
+  order: z.array(Id).optional(),
+})
+export type QueryStored = z.infer<typeof QueryStored>
+
+/**
+ * A query's own picks applied to the ids its rule returned, in the rule's order: excluded entries
+ * leave, `limit` cuts what remains of the rule's own results, pinned entries not among those kept
+ * join at the end (an id both excluded and pinned stays out), and a hand-set `order` puts its
+ * entries first. So a pin survives the limit. `total` counts the rule's matches after exclusions
+ * plus the pins not among them, before `limit`. The platform and the fake both call this, so a
+ * placement reads the same everywhere. `exists` says whether a pinned id names an entry the read
+ * may show.
+ */
+export const applyQueryPicks = (ids: Id[], q: QueryStored, exists: (id: Id) => boolean): { ids: Id[]; total: number } => {
+  const excluded = new Set((q.exclude ?? []).map(String))
+  const matched = ids.filter((id) => !excluded.has(String(id)))
+  const matches = new Set(matched.map(String))
+  const out = q.limit ? matched.slice(0, q.limit) : [...matched]
+  const present = new Map(out.map((id) => [String(id), id]))
+  let pinsBeyond = 0
+  for (const id of q.pin ?? [])
+    if (!present.has(String(id)) && !excluded.has(String(id)) && exists(id)) {
+      out.push(id)
+      present.set(String(id), id)
+      if (!matches.has(String(id))) pinsBeyond++
+    }
+  const total = matched.length + pinsBeyond
+  if (!q.order?.length) return { ids: out, total }
+  const first = q.order.filter((id) => present.has(String(id))).map((id) => present.get(String(id))!)
+  const leading = new Set(first.map(String))
+  return { ids: [...first, ...out.filter((id) => !leading.has(String(id)))], total }
+}
+
+const stored = (o: O) =>
+  QueryStored.superRefine((q, ctx) => {
+    const fields = o.targetFields
+    q.where?.forEach((w, i) => {
+      const el = fields?.[w.field]
+      if (fields && !el) return ctx.addIssue({ code: 'custom', path: ['where', i, 'field'], message: `The target has no field "${w.field}".`, params: { code: 'unknown-field' } })
+      if (el && !FILTERABLE.includes(el)) return ctx.addIssue({ code: 'custom', path: ['where', i, 'field'], message: 'Only choice, boolean, relation, date and number fields can be filtered.', params: { code: 'not-filterable' } })
+      if ((w.op === 'in' || w.op === 'not-in') && !Array.isArray(w.value)) ctx.addIssue({ code: 'invalid_type', path: ['where', i, 'value'], message: 'in and not-in take a list of values.', expected: 'array', input: w.value } as never)
+      if ((w.op === 'eq' || w.op === 'neq') && (w.value === undefined || Array.isArray(w.value))) ctx.addIssue({ code: 'invalid_type', path: ['where', i, 'value'], message: 'eq and neq take one value.', expected: 'string', input: w.value } as never)
+    })
+    if (q.sort && q.sort !== 'manual') {
+      const el = fields?.[q.sort.field]
+      if (fields && !el) ctx.addIssue({ code: 'custom', path: ['sort', 'field'], message: `The target has no field "${q.sort.field}".`, params: { code: 'unknown-field' } })
+      else if (el && !SORTABLE.includes(el)) ctx.addIssue({ code: 'custom', path: ['sort', 'field'], message: 'Only text, date and number fields can be sorted.', params: { code: 'not-sortable' } })
+    }
+    for (const k of ['exclude', 'pin', 'order'] as const) {
+      const ids = q[k]
+      if (ids && new Set(ids.map(String)).size !== ids.length)
+        ctx.addIssue({ code: 'custom', path: [k], message: 'Each entry may be listed once.', params: { code: 'duplicate' } })
+    }
+  })
+const expand = (v: QueryStored, o: O, ctx: ExpandCtx): EntriesRead => ({ ...ctx.query(o.to, v), ...(ctx.draft ? { $path: ctx.at } : {}) })
+
+export const query = defineElement({
+  id: 'u90/query',
+  version: 1,
+  label: 'Query',
+  placement: 'content',
+  options: QueryOptions,
+  seed: stored,
+  stored,
+  read: () => EntriesReadSchema,
+  complete: () => [],
+  refs: (v, o): Ref[] => [{ kind: 'query', collection: o.to, query: v }],
+  toStored: async (s) => s,
+  expand,
+  expandSeed: expand,
+  toText: () => '',
+  translatable: () => [],
+  translation: null,
+  empty: () => ({}),
+  upgrade: {},
+})

package/src/elements/leaves/relation.ts

@@ -0,0 +1,69 @@
+import { z, type ZodType } from 'zod'
+import { EntryReadSchema, Id, defineElement, requiredIssue, type EntryRead, type ExpandCtx, type Ref, type SeedCtx } from '../define'
+import { path } from '../path'
+
+/** Seeds name entries by key inside the target collection, or give an id. */
+export const EntryRef = z.union([Id, z.strictObject({ $ref: z.strictObject({ collection: z.string().min(1).optional(), key: z.string().min(1) }) })])
+export const resolveEntryRef = (ref: z.infer<typeof EntryRef>, collection: string, ctx: SeedCtx) =>
+  typeof ref === 'object' ? ctx.resolveEntry(ref.$ref.collection ?? collection, ref.$ref.key) : ref
+export const uniqueIds = (ids: unknown[], ctx: z.RefinementCtx) => {
+  if (new Set(ids.map(String)).size !== ids.length)
+    ctx.addIssue({ code: 'custom', message: 'Each entry may be referenced once.', params: { code: 'duplicate' } })
+}
+
+export const RelationOptions = z
+  .strictObject({
+    to: z.string().min(1),
+    cardinality: z.enum(['many-to-one', 'one-to-one', 'many-to-many', 'one-to-many']),
+    inverseOf: z.string().min(1).optional(),
+    depth: z.int().min(0).max(3).default(1),
+  })
+  .refine((o) => o.cardinality !== 'one-to-many' || o.inverseOf, { path: ['inverseOf'], message: 'one-to-many is always the derived side: name the many-to-one field on the target.' })
+type O = z.infer<typeof RelationOptions>
+/** The derived side stores nothing; its value is read from the target collection. */
+export const isDerived = (o: O) => o.cardinality === 'one-to-many' || o.inverseOf !== undefined
+const isMany = (o: O) => o.cardinality === 'many-to-many' || o.cardinality === 'one-to-many'
+
+const stored = (o: O) => (isDerived(o) ? z.null() : isMany(o) ? z.array(Id).superRefine(uniqueIds) : Id.nullable())
+type Stored = Id | Id[] | null
+type SeedValue = z.infer<typeof EntryRef> | z.infer<typeof EntryRef>[] | null
+const seed = (o: O): ZodType<SeedValue> => (isDerived(o) ? z.null() : isMany(o) ? z.array(EntryRef) : EntryRef.nullable())
+const read = (o: O) => (isMany(o) ? z.array(EntryReadSchema) : EntryReadSchema.nullable())
+const selfId = (at: string) => path.parse(at).id
+
+const expand = (v: Stored, o: O, ctx: ExpandCtx): EntryRead | EntryRead[] | null => {
+  if (isDerived(o)) {
+    const inverse = ctx.inverse(o.to, o.inverseOf!, selfId(ctx.at))
+    return isMany(o) ? inverse : (inverse[0] ?? null)
+  }
+  if (Array.isArray(v)) return v.map((id) => ctx.entry(o.to, id, o.depth))
+  return v === null ? null : ctx.entry(o.to, v, o.depth)
+}
+
+export const relation = defineElement({
+  id: 'u90/relation',
+  version: 1,
+  label: 'Relation',
+  placement: 'collection',
+  options: RelationOptions,
+  seed,
+  stored,
+  read,
+  complete: (v, o, field) => (isDerived(o) ? [] : requiredIssue(Array.isArray(v) ? v.length > 0 : v != null, field)),
+  refs: (v, o, at): Ref[] => {
+    if (isDerived(o)) return [{ kind: 'inverse', collection: o.to, field: o.inverseOf!, id: selfId(at) }]
+    if (Array.isArray(v)) return v.map((id) => ({ kind: 'entry', collection: o.to, id, depth: o.depth }))
+    return v === null ? [] : [{ kind: 'entry', collection: o.to, id: v, depth: o.depth }]
+  },
+  toStored: async (s, o, ctx) => {
+    if (isDerived(o) || s === null) return null
+    return Array.isArray(s) ? s.map((r) => resolveEntryRef(r, o.to, ctx)) : resolveEntryRef(s, o.to, ctx)
+  },
+  expand,
+  expandSeed: (s, o, ctx) => expand(isDerived(o) || s === null ? null : Array.isArray(s) ? s.filter((r) => typeof r !== 'object') as Id[] : typeof s === 'object' ? null : s, o, ctx),
+  toText: () => '',
+  translatable: () => [],
+  translation: null,
+  empty: (o) => (isDerived(o) ? null : isMany(o) ? [] : null),
+  upgrade: {},
+})

package/src/elements/leaves/rich-text.ts

@@ -0,0 +1,155 @@
+import { z } from 'zod'
+import { defineElement, requiredIssue, type ExpandCtx, type Ref } from '../define'
+import { TOKEN, textOfRead, tokenKeys } from '../tokens'
+import { LinkTo, hrefOf } from './link'
+
+/** Lexical's inline format bits — the same values `lexical.ts` exports; restated so this module has no runtime import. */
+const BITS = { bold: 1, italic: 2, strikethrough: 4, underline: 8, code: 16 } as const
+const MARKS = ['bold', 'italic', 'underline', 'strikethrough', 'code', 'link'] as const
+const BLOCKS = ['paragraph', 'heading', 'list', 'quote'] as const
+const HEADINGS = ['h2', 'h3', 'h4'] as const
+
+export const RichTextOptions = z.strictObject({
+  inline: z.boolean().default(false),
+  blocks: z.array(z.enum(BLOCKS)).min(1).default(['paragraph', 'heading', 'list']),
+  headings: z.array(z.enum(HEADINGS)).min(1).default(['h2', 'h3']),
+  marks: z.array(z.enum(MARKS)).default(['bold', 'italic', 'underline', 'link']),
+})
+type O = z.infer<typeof RichTextOptions>
+
+const common = { direction: z.enum(['ltr', 'rtl']).nullable().default('ltr'), format: z.string().default(''), indent: z.int().default(0), version: z.int().default(1) }
+const TextNode = z.object({ type: z.literal('text'), text: z.string(), format: z.int().nonnegative().default(0), detail: z.int().default(0), mode: z.string().default('normal'), style: z.string().default('') , version: z.int().default(1) })
+const LineBreak = z.object({ type: z.literal('linebreak'), version: z.int().default(1) })
+const LinkNode = z.object({ type: z.literal('link'), fields: z.object({ to: LinkTo, newTab: z.boolean().default(false) }), children: z.array(z.union([TextNode, LineBreak])), ...common })
+const inlines = (o: O) => z.array(o.marks.includes('link') ? z.union([TextNode, LineBreak, LinkNode]) : z.union([TextNode, LineBreak]))
+const Paragraph = (o: O) => z.object({ type: z.literal('paragraph'), children: inlines(o), textFormat: z.int().default(0), ...common })
+const Heading = (o: O) => z.object({ type: z.literal('heading'), tag: z.enum(o.headings as [string, ...string[]]), children: inlines(o), ...common })
+const Quote = (o: O) => z.object({ type: z.literal('quote'), children: inlines(o), ...common })
+const ListItem = (o: O) => z.object({ type: z.literal('listitem'), children: inlines(o), value: z.int().default(1), ...common })
+const List = (o: O) => z.object({ type: z.literal('list'), listType: z.enum(['bullet', 'number']), tag: z.enum(['ul', 'ol']), start: z.int().default(1), children: z.array(ListItem(o)), ...common })
+const blockSchemas = (o: O) => {
+  const by = { paragraph: Paragraph(o), heading: Heading(o), list: List(o), quote: Quote(o) }
+  const chosen = o.blocks.map((b) => by[b])
+  return chosen.length === 1 ? chosen[0] : z.union(chosen as z.ZodTypeAny[] as [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]])
+}
+const allowedMask = (o: O) => o.marks.reduce((m, k) => (k === 'link' ? m : m | BITS[k]), 0)
+
+type Node = { type: string; text?: string; format?: number | string; children?: Node[]; fields?: Record<string, unknown> } & Record<string, unknown>
+const eachText = (node: Node, path: (string | number)[], f: (n: Node, path: (string | number)[]) => void) => {
+  if (node.type === 'text') f(node, path)
+  node.children?.forEach((c, i) => eachText(c, [...path, 'children', i], f))
+}
+const eachLink = (node: Node, f: (n: Node) => void) => {
+  if (node.type === 'link') f(node)
+  node.children?.forEach((c) => eachLink(c, f))
+}
+
+const stored = (o: O) =>
+  z
+    .object({ root: z.object({ type: z.literal('root'), children: z.array(blockSchemas(o)), ...common }) })
+    .superRefine((v, ctx) => {
+      const root = v.root as unknown as Node
+      if (o.inline && (root.children!.length !== 1 || root.children![0].type !== 'paragraph'))
+        ctx.addIssue({ code: 'custom', path: ['root', 'children'], message: 'Inline text is a single paragraph.', params: { code: 'inline' } })
+      const mask = allowedMask(o)
+      eachText(root, ['root'], (n, path) => {
+        if (typeof n.format === 'number' && (n.format & ~mask) !== 0)
+          ctx.addIssue({ code: 'custom', path: [...path, 'format'], message: `Only these marks are allowed: ${o.marks.join(', ')}.`, params: { code: 'marks' } })
+      })
+    })
+    .nullable()
+type Stored = z.infer<ReturnType<typeof stored>>
+/** The widest options: every block, and a link in every inline run. */
+const WIDE: O = { inline: false, blocks: [...BLOCKS], headings: [...HEADINGS], marks: [...MARKS] }
+/** The same tree with all four blocks, any heading tag and a link anywhere inline, so narrowed options never blank content. */
+const SHAPE = z
+  .object({ root: z.object({ type: z.literal('root'), children: z.array(z.union([Paragraph(WIDE), Heading(WIDE).extend({ tag: z.string() }), List(WIDE), Quote(WIDE)])), ...common }) })
+  .nullable()
+
+export const richTextToPlain = (v: Stored): string =>
+  v ? (v.root.children as unknown as Node[]).map((b) => { const parts: string[] = []; eachText(b, [], (n) => parts.push(n.text ?? '')); return parts.join('') }).join('\n') : ''
+
+export type RichTextRead = ({ root: unknown; $path?: string }) | null
+const expand = (v: Stored, o: O, ctx: ExpandCtx): RichTextRead => {
+  if (v === null) return null
+  const root = structuredClone(v.root) as unknown as Node
+  eachLink(root, (n) => { const fields = n.fields as { to: z.infer<typeof LinkTo> }; Object.assign(fields, hrefOf(fields.to, ctx)) })
+  const split = (node: Node) => {
+    if (!node.children) return
+    node.children.forEach(split)
+    node.children = node.children.flatMap((c) => {
+      if (c.type !== 'text' || typeof c.text !== 'string' || !TOKEN.test(c.text)) return [c]
+      TOKEN.lastIndex = 0
+      const out: Node[] = []
+      let last = 0
+      for (const m of c.text.matchAll(TOKEN)) {
+        if (m.index! > last) out.push({ ...c, text: c.text.slice(last, m.index) })
+        const resolved = textOfRead(ctx.single(m[1]))
+        out.push(resolved === undefined ? { ...c, text: m[0] } : { type: 'single', key: m[1], text: resolved, format: c.format ?? 0, version: 1 })
+        last = m.index! + m[0].length
+      }
+      if (last < c.text.length) out.push({ ...c, text: c.text.slice(last) })
+      return out
+    })
+  }
+  split(root)
+  return { root, ...(ctx.draft ? { $path: ctx.at } : {}) }
+}
+
+const linkNodes = (v: NonNullable<Stored>): Node[] => { const out: Node[] = []; eachLink(v.root as unknown as Node, (n) => out.push(n)); return out }
+const tokensOf = (v: NonNullable<Stored>): string => { const keys: string[] = []; eachText(v.root as unknown as Node, [], (n) => keys.push(...tokenKeys(n.text ?? ''))); return keys.sort().join(',') }
+/**
+ * A translation may reword and reformat, never repoint: it lands only when it holds as many links as the
+ * base and the same `{single}` tokens, and each link keeps the base link's fields (destination, new tab).
+ */
+const landTranslation = (base: Stored | undefined, t: Stored): Stored | undefined => {
+  if (!base || !t) return undefined
+  const from = linkNodes(base)
+  const copy = structuredClone(t)
+  const into = linkNodes(copy)
+  if (from.length !== into.length || tokensOf(base) !== tokensOf(copy)) return undefined
+  from.forEach((n, i) => { into[i].fields = structuredClone(n.fields) })
+  return copy
+}
+
+export const richText = defineElement({
+  id: 'u90/rich-text',
+  version: 1,
+  label: 'Rich text',
+  placement: 'any',
+  options: RichTextOptions,
+  seed: stored,
+  stored,
+  shape: () => SHAPE,
+  read: () => z.object({ root: z.unknown(), $path: z.string().optional() }).nullable(),
+  complete: (v, _o, field) => requiredIssue(richTextToPlain(v ?? null).trim() !== '', field),
+  refs: (v) => {
+    if (!v) return []
+    const refs: Ref[] = []
+    const root = v.root as unknown as Node
+    eachText(root, [], (n) => tokenKeys(n.text ?? '').forEach((key) => refs.push({ kind: 'single', key })))
+    eachLink(root, (n) => {
+      const to = (n.fields as { to: z.infer<typeof LinkTo> }).to
+      if ('page' in to) refs.push({ kind: 'page', id: to.page })
+      else if ('entry' in to) refs.push({ kind: 'entry', collection: to.entry.collection, id: to.entry.id, depth: 0 })
+    })
+    return refs
+  },
+  toStored: async (seed) => seed,
+  expand,
+  expandSeed: expand,
+  toText: richTextToPlain,
+  translatable: (v) => {
+    const out: { path: (string | number)[]; value: string }[] = []
+    if (v) eachText(v.root as unknown as Node, ['root'], (n, path) => { if (n.text) out.push({ path: [...path, 'text'], value: n.text }) })
+    return out
+  },
+  translation: {
+    applies: () => true,
+    value: (o) => stored(o),
+    pick: (v) => v,
+    apply: (base, t) => landTranslation(base, t),
+  },
+  empty: () => null,
+  upgrade: {},
+})

package/src/elements/leaves/selection.ts

@@ -0,0 +1,40 @@
+import { z, type ZodType } from 'zod'
+import { EntryReadSchema, Id, defineElement, requiredIssue, type EntryRead, type ExpandCtx, type Ref } from '../define'
+import { EntryRef, resolveEntryRef, uniqueIds } from './relation'
+
+export const SelectionOptions = z.strictObject({ to: z.string().min(1), many: z.boolean().default(false), max: z.int().positive().optional(), depth: z.int().min(0).max(3).default(1) })
+type O = z.infer<typeof SelectionOptions>
+/** How a selection and a query read: the entries in order, how many there are, and `$path` in draft. */
+export type EntriesRead = { entries: EntryRead[]; total: number; $path?: string }
+export const EntriesReadSchema = z.object({ entries: z.array(EntryReadSchema), total: z.number(), $path: z.string().optional() })
+
+const stored = (o: O) => (o.many ? (o.max ? z.array(Id).max(o.max) : z.array(Id)).superRefine(uniqueIds) : Id.nullable())
+type SeedValue = z.infer<typeof EntryRef> | z.infer<typeof EntryRef>[] | null
+const seed = (o: O): ZodType<SeedValue> => (o.many ? z.array(EntryRef) : EntryRef.nullable())
+const ids = (v: Id | Id[] | null) => (Array.isArray(v) ? v : v === null ? [] : [v])
+/** Every selected entry is read, so `total` is the number of entries — the same shape a query reads. */
+const expand = (v: Id | Id[] | null, o: O, ctx: ExpandCtx): EntriesRead => {
+  const entries = ids(v).map((id) => ctx.entry(o.to, id, o.depth))
+  return { entries, total: entries.length, ...(ctx.draft ? { $path: ctx.at } : {}) }
+}
+
+export const selection = defineElement({
+  id: 'u90/selection',
+  version: 1,
+  label: 'Selection',
+  placement: 'content',
+  options: SelectionOptions,
+  seed,
+  stored,
+  read: () => EntriesReadSchema,
+  complete: (v, _o, field) => requiredIssue(ids(v ?? null).length > 0, field),
+  refs: (v, o): Ref[] => ids(v).map((id) => ({ kind: 'entry', collection: o.to, id, depth: o.depth })),
+  toStored: async (s, o, ctx) => (Array.isArray(s) ? s.map((r) => resolveEntryRef(r, o.to, ctx)) : s === null ? null : resolveEntryRef(s, o.to, ctx)),
+  expand,
+  expandSeed: (s, o, ctx) => expand(Array.isArray(s) ? (s.filter((r) => typeof r !== 'object') as Id[]) : typeof s === 'object' ? null : s, o, ctx),
+  toText: () => '',
+  translatable: () => [],
+  translation: null,
+  empty: (o) => (o.many ? [] : null),
+  upgrade: {},
+})

package/src/elements/leaves/single.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod'
+import { defineElement } from '../define'
+
+export const SingleOptions = z.strictObject({ key: z.string().regex(/^[a-z][a-zA-Z0-9_-]*$/) })
+type O = z.infer<typeof SingleOptions>
+/** Nothing is stored on the block: the declaration fixes the key. Only `null` (or absence) is valid. */
+const stored = z.null()
+
+export const single = defineElement({
+  id: 'u90/single',
+  version: 1,
+  label: 'Single',
+  placement: 'any',
+  options: SingleOptions,
+  seed: () => stored,
+  stored: () => stored,
+  read: () => z.unknown(),
+  /** `validateSchema` rejects a key that names no Single; whether the Single has a value is not checked by the registry — it needs data this leaf does not have. */
+  complete: () => [],
+  refs: (_v, o) => [{ kind: 'single', key: o.key }],
+  toStored: async () => null,
+  expand: (_v, o, ctx) => ctx.single(o.key) ?? null,
+  expandSeed: (_v, o, ctx) => ctx.single(o.key) ?? null,
+  toText: () => '',
+  translatable: () => [],
+  translation: null,
+  empty: () => null,
+  upgrade: {},
+})