@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/elements/leaves/image.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod'
+import { Id, MediaAssetSchema, defineElement, requiredIssue, type ExpandCtx, type ImageCrop, type MediaAsset, type MediaRecord, type Ref, type SeedCtx } from '../define'
+
+const pct = z.number().min(0).max(100)
+export const FocalPoint = z.strictObject({ x: pct, y: pct })
+export const Crop = z
+  .strictObject({ x: z.number().min(0), y: z.number().min(0), width: z.number().positive(), height: z.number().positive() })
+  .refine((c) => c.x + c.width <= 100 && c.y + c.height <= 100, { message: 'Crop must be a finite positive rectangle inside the original image.', params: { code: 'crop' } })
+const insideCrop = (p: { x: number; y: number }, c: ImageCrop) => p.x >= c.x && p.x <= c.x + c.width && p.y >= c.y && p.y <= c.y + c.height
+/**
+ * The two cross-field rules shared by every geometry-shaped schema: a stored/seeded `geometry()`, the
+ * top-level of `imageStored`/`imageSeed`, and (via nesting) each of their variants. Nesting a schema that
+ * calls this from its own `superRefine` auto-prefixes the issue path with that field's key, so a variant
+ * built from `geometry(Id)` or `seedGeometry` reports at `variants.<name>.focalPoint` with no extra work here.
+ */
+const crossFieldRules = (v: { focalPoint: { x: number; y: number } | null; crop: ImageCrop | null; alt?: string; decorative?: boolean }, ctx: z.RefinementCtx) => {
+  if (v.focalPoint && v.crop && !insideCrop(v.focalPoint, v.crop))
+    ctx.addIssue({ code: 'custom', path: ['focalPoint'], message: 'Focal point must lie inside the crop.', params: { code: 'focal-outside-crop' } })
+  if (v.decorative && v.alt !== '')
+    ctx.addIssue({ code: 'custom', path: ['alt'], message: 'Decorative images must have empty alternative text.', params: { code: 'decorative-alt' } })
+}
+
+const positiveInt = z.int().positive()
+export const ImageConstraints = z.strictObject({
+  mimeTypes: z.array(z.string().regex(/^image\/[a-z0-9.+-]+$/i)).min(1).optional(),
+  maxBytes: positiveInt.optional(),
+  minWidth: positiveInt.optional(),
+  minHeight: positiveInt.optional(),
+  cropAspectRatios: z.array(z.number().positive()).min(1).optional(),
+})
+const VariantKey = z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/).refine((k) => !['constructor', 'prototype', '__proto__'].includes(k), 'Variant needs a safe name.')
+export const ImageOptions = z.strictObject({
+  constraints: ImageConstraints.optional(),
+  variants: z.record(VariantKey, z.strictObject({ media: z.string().trim().min(1), constraints: ImageConstraints.optional() })).default({}),
+})
+type O = z.infer<typeof ImageOptions>
+
+const geometry = <A extends z.ZodTypeAny>(asset: A) =>
+  z.strictObject({ asset, crop: Crop.nullable(), focalPoint: FocalPoint.nullable() }).superRefine((v, ctx) => crossFieldRules(v, ctx))
+const variantsShape = <V extends z.ZodTypeAny>(o: O, variant: V) =>
+  z.strictObject(Object.fromEntries(Object.keys(o.variants).map((k) => [k, variant.optional()])))
+
+export const imageStored = (o: O) =>
+  z
+    .strictObject({
+      ...geometry(Id).shape,
+      alt: z.string(),
+      decorative: z.boolean(),
+      caption: z.string().nullable(),
+      variants: variantsShape(o, geometry(Id)),
+    })
+    .superRefine((v, ctx) => crossFieldRules(v, ctx))
+    .nullable()
+export type ImageStored = z.infer<ReturnType<typeof imageStored>>
+
+const SeedAsset = z.union([Id, z.strictObject({ source: z.string().trim().min(1) })])
+const seedGeometry = z
+  .strictObject({ asset: SeedAsset, crop: Crop.nullable().default(null), focalPoint: FocalPoint.nullable().default(null) })
+  .superRefine((v, ctx) => crossFieldRules(v, ctx))
+export const imageSeed = (o: O) =>
+  z
+    .strictObject({
+      ...seedGeometry.shape,
+      alt: z.string().default(''),
+      decorative: z.boolean().default(false),
+      caption: z.string().nullable().default(null).transform((c) => (c === '' ? null : c)),
+      variants: variantsShape(o, seedGeometry).default({}),
+    })
+    .superRefine((v, ctx) => crossFieldRules(v, ctx))
+    .nullable()
+export type ImageSeed = z.infer<ReturnType<typeof imageSeed>>
+
+export type ImageAsset = MediaAsset
+export type ImageReadVariant = { asset: ImageAsset | null; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null; rendition: { url: string; width: number | null; height: number | null; blurDataURL?: string } | null; status: 'ready' | 'missing' | 'processing' | 'error' }
+export type ImageRead = (ImageReadVariant & { alt: string; decorative: boolean; caption: string | null; variants: Record<string, ImageReadVariant>; $path?: string }) | null
+const renditionRead = z.object({ url: z.string(), width: z.number().nullable(), height: z.number().nullable(), blurDataURL: z.string().optional() })
+const variantRead = z.object({ asset: MediaAssetSchema.nullable(), crop: Crop.nullable(), focalPoint: FocalPoint.nullable(), rendition: renditionRead.nullable(), status: z.enum(['ready', 'missing', 'processing', 'error']) })
+const imageRead = z.object({ ...variantRead.shape, alt: z.string(), decorative: z.boolean(), caption: z.string().nullable(), variants: z.record(z.string(), variantRead), $path: z.string().optional() }).nullable()
+
+const sameCrop = (a: ImageCrop | null, b: ImageCrop | null) => (a === null && b === null) || (!!a && !!b && a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height)
+const pick = (m: MediaRecord): ImageAsset => { const { renditions: _r, ...asset } = m; return asset }
+const readVariant = (v: { asset: Id; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null }, ctx: ExpandCtx): ImageReadVariant => {
+  const m = ctx.media(v.asset)
+  if (!m) return { asset: null, crop: v.crop, focalPoint: v.focalPoint, rendition: null, status: 'missing' }
+  const r = m.renditions?.find((x) => sameCrop(x.crop, v.crop))
+  if (r) return { asset: pick(m), crop: v.crop, focalPoint: v.focalPoint, rendition: r.status === 'ready' ? { url: r.url, width: r.width, height: r.height, ...(r.blurDataURL ? { blurDataURL: r.blurDataURL } : {}) } : null, status: r.status }
+  if (v.crop === null) return { asset: pick(m), crop: null, focalPoint: v.focalPoint, rendition: { url: m.url, width: m.width, height: m.height, ...(m.blurDataURL ? { blurDataURL: m.blurDataURL } : {}) }, status: 'ready' }
+  return { asset: pick(m), crop: v.crop, focalPoint: v.focalPoint, rendition: null, status: 'processing' }
+}
+export const expandImage = (v: ImageStored, _o: O, ctx: ExpandCtx): ImageRead =>
+  v === null
+    ? null
+    : {
+        ...readVariant(v, ctx),
+        alt: v.alt,
+        decorative: v.decorative,
+        caption: v.caption,
+        variants: Object.fromEntries(Object.entries(v.variants).filter(([, x]) => x).map(([k, x]) => [k, readVariant(x!, ctx)])),
+        ...(ctx.draft ? { $path: ctx.at } : {}),
+      }
+
+/** A seed's `{ source }` reads as an asset served from that path, until seeding imports it. */
+const sourceCtx = (ctx: ExpandCtx, sources: Map<string, string>): ExpandCtx => ({
+  ...ctx,
+  media: (id) => {
+    const source = sources.get(String(id))
+    return source ? { id, url: source, mimeType: '', width: null, height: null, filename: source.split('/').pop() ?? source } : ctx.media(id)
+  },
+})
+const toSeedStored = (s: NonNullable<ImageSeed>, sources: Map<string, string>): NonNullable<ImageStored> => {
+  const lower = (g: { asset: Id | { source: string }; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null }) => {
+    if (typeof g.asset === 'object') { const key = `seed:${g.asset.source}`; sources.set(key, g.asset.source); return { ...g, asset: key } }
+    return g as { asset: Id; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null }
+  }
+  return { ...lower(s), alt: s.alt, decorative: s.decorative, caption: s.caption, variants: Object.fromEntries(Object.entries(s.variants).filter(([, g]) => g).map(([k, g]) => [k, lower(g!)])) }
+}
+
+export const imageToStored = async (s: ImageSeed, o: O, ctx: SeedCtx): Promise<ImageStored> => {
+  if (s === null) return null
+  const resolve = async (g: { asset: Id | { source: string }; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null }) => ({ ...g, asset: typeof g.asset === 'object' ? await ctx.importAsset(g.asset.source) : g.asset })
+  const variants: Record<string, { asset: Id; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null }> = {}
+  for (const [k, g] of Object.entries(s.variants)) if (g) variants[k] = await resolve(g)
+  return imageStored(o).parse({ ...(await resolve(s)), alt: s.alt, decorative: s.decorative, caption: s.caption, variants })
+}
+
+const mediaRefs = (v: ImageStored): Ref[] => (v ? [{ kind: 'media', id: v.asset }, ...Object.values(v.variants).filter((x) => x).map((x) => ({ kind: 'media' as const, id: x!.asset }))] : [])
+
+export const image = defineElement({
+  id: 'u90/image',
+  version: 1,
+  label: 'Image',
+  placement: 'any',
+  options: ImageOptions,
+  seed: imageSeed,
+  stored: imageStored,
+  read: () => imageRead,
+  complete: (v, _o, field) => {
+    if (v == null) return requiredIssue(false, field)
+    return !v.decorative && !v.alt.trim() ? [{ path: ['alt'], code: 'alt', message: 'Meaningful images need alternative text for publication.' }] : []
+  },
+  refs: mediaRefs,
+  toStored: imageToStored,
+  expand: expandImage,
+  expandSeed: (s, o, ctx) => { if (s === null) return null; const sources = new Map<string, string>(); return expandImage(toSeedStored(s, sources), o, sourceCtx(ctx, sources)) },
+  toText: (v) => (v ? [v.decorative ? '' : v.alt, v.caption ?? ''].filter(Boolean).join(' ') : ''),
+  translatable: (v) => (v ? [...(!v.decorative && v.alt ? [{ path: ['alt'], value: v.alt }] : []), ...(v.caption ? [{ path: ['caption'], value: v.caption }] : [])] : []),
+  translation: {
+    applies: () => true,
+    value: () => z.object({ alt: z.string().min(1).optional(), caption: z.string().optional() }).refine((t) => t.alt !== undefined || t.caption !== undefined, 'An image translation names its alt text or caption.'),
+    pick: (v) => {
+      if (!v) return null
+      const alt = !v.decorative && v.alt ? v.alt : undefined
+      const caption = v.caption ? v.caption : undefined
+      return alt === undefined && caption === undefined ? null : { ...(alt !== undefined ? { alt } : {}), ...(caption !== undefined ? { caption } : {}) }
+    },
+    apply: (base, t) => (base ? { ...base, ...(t.alt !== undefined && !base.decorative ? { alt: t.alt } : {}), ...(t.caption !== undefined ? { caption: t.caption } : {}) } : undefined),
+  },
+  empty: () => null,
+  upgrade: {},
+})

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, $pins: (v.pin ?? []).map(String) } : {}) })
+
+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: {},
+})