@embedpdf/engine-core 3.0.0-next.13 → 3.0.0-next.15

package/dist/validation.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.cjs","names":["declarationOf","FileAnnotationDraftSchema","KIND_BY_SUBTYPE","EngineError","EngineErrorCode","fileAnnotationPatchSchemaOf","pdfPrepareAnnotationDraft","pdfDeriveAnnotationDraft","pdfPrepareAnnotationPatch","pdfDeriveAnnotationPatch","bundlePageMapping","draftOf","annotationKey","encodePageKey","pageRefsIn","declarationOf","AnnotationDraftSchema","EngineError","EngineErrorCode","mapPageRefs","bundlePageMapping","pageRefsIn","annotationKey","fieldValueOf","encodeFieldRefKey","fieldMatches","fieldScriptOf","WIDGET_ACTION_EVENTS","actionWriteOf","needsScriptRight","mapPageRefs","WIDGET_FLAG_NAMES","EngineError","EngineErrorCode","FormFieldDraftSchema"],"sources":["../src/annotation/checkWrite.ts","../src/transfer/planAnnotationImport.ts","../src/transfer/planFormImport.ts"],"sourcesContent":["/**\n * The checks every annotation write runs before its first write, on both\n * engines: the prepared values against their kind's schema, not only the\n * names. A value the schema refuses is `InvalidArg` naming the field. A check\n * only accepts or refuses: it never adds, drops or changes a field, so the\n * engine writes what a viewer predicts (prepare, check, derive; the viewer\n * runs the same two steps without schema validation, `resolve/`). Built with\n * zod, so it runs where the engine does (its worker, the server), never on\n * the page: `@embedpdf/engine-core/validation` exports it.\n */\nimport type { z } from 'zod';\n\nimport {\n  declarationOf,\n  FileAnnotationDraftSchema,\n  fileAnnotationPatchSchemaOf,\n  KIND_BY_SUBTYPE,\n  type AnnotationDraft,\n  type Annotation,\n  type AnnotationPatch,\n} from './kinds';\nimport {\n  pdfDeriveAnnotationDraft,\n  pdfPrepareAnnotationDraft,\n  type DraftResolveOptions,\n} from './resolve/resolveAnnotationDraft';\nimport {\n  pdfDeriveAnnotationPatch,\n  pdfPrepareAnnotationPatch,\n  type ResolveOptions,\n} from './resolve/resolveAnnotationPatch';\nimport { EngineError } from '../errors/EngineError';\nimport { EngineErrorCode } from '../errors/EngineErrorCode';\nimport type { PdfCoordinates } from '../pageSpace/coordinates';\n\n/**\n * A prepared create's data checked against its kind's schema. The caller\n * writes its own data, not the schema's output, so nothing is reshaped on its\n * way in.\n */\nexport function assertAnnotationDraft(\n  draft: AnnotationDraft<PdfCoordinates>,\n  options: {\n    /**\n     * Link fields the caller has taken out of the draft and links itself (a\n     * change set's `reply` and popup `parent`); they aren't checked here.\n     */\n    linked?: readonly string[];\n  } = {},\n): void {\n  const declaration = declarationOf(String(draft.subtype));\n  const linked = options.linked ?? [];\n  const schema =\n    declaration && linked.length > 0\n      ? (declaration.fileSchemas.create as unknown as z.AnyZodObject).omit(\n          Object.fromEntries(linked.map((name) => [name, true])),\n        )\n      : FileAnnotationDraftSchema;\n  const checked = schema.safeParse(draft);\n  if (!checked.success) throw invalidWrite(checked.error, `${String(draft.subtype)} create`);\n}\n\n/**\n * A prepared update's data (`pdfPrepareAnnotationPatch`) checked against the\n * kind of `current`. A `readBack()` value still in it is a change, as\n * preparation drops one sent back as it reads, so one a write can't make is\n * refused; the rest is checked against the kind's update schema.\n */\nexport function assertAnnotationPatch(\n  current: Annotation<PdfCoordinates>,\n  prepared: AnnotationPatch<PdfCoordinates>,\n): void {\n  if (current.subtype === 'unsupported') return;\n  const values = prepared as Record<string, unknown>;\n  for (const [name, write] of Object.entries(KIND_BY_SUBTYPE[current.subtype].readBackWrites)) {\n    const value = values[name];\n    if (value === undefined || write?.safeParse(value).success) continue;\n    throw new EngineError(\n      EngineErrorCode.InvalidArg,\n      write\n        ? `${current.subtype} update field '${name}': this value can be read but not written; send it back unchanged or replace it`\n        : `${current.subtype} update field '${name}': the engine works this out; send it back unchanged or leave it out`,\n      { details: { field: name } },\n    );\n  }\n  const parsed = fileAnnotationPatchSchemaOf(current.subtype).safeParse(prepared);\n  if (!parsed.success) throw invalidWrite(parsed.error, `${current.subtype} update`);\n}\n\n/**\n * The draft the engine writes for `draft`, in the file's coordinates:\n * prepared (`pdfPrepareAnnotationDraft`), checked against its kind, and\n * every field that follows from it stated (`pdfDeriveAnnotationDraft`). A\n * viewer predicts the same without schema validation\n * (`pdfPredictAnnotationDraft`).\n *\n * Throws `InvalidArg` for a draft the engine refuses. Pure: it reads nothing\n * but its arguments.\n */\nexport function pdfResolveAnnotationDraft(\n  draft: AnnotationDraft<PdfCoordinates>,\n  options: DraftResolveOptions = {},\n): AnnotationDraft<PdfCoordinates> {\n  const prepared = pdfPrepareAnnotationDraft(draft);\n  assertAnnotationDraft(prepared, { linked: options.linked ?? [] });\n  return pdfDeriveAnnotationDraft(prepared, options);\n}\n\n/**\n * The patch the engine writes for `patch` on `current`, in the file's\n * coordinates: prepared (`pdfPrepareAnnotationPatch`), checked against its\n * kind (`assertAnnotationPatch`), and every field that follows from it\n * stated (`pdfDeriveAnnotationPatch`). A viewer predicts the same without\n * schema validation (`pdfPredictAnnotationPatch`).\n *\n * Throws `InvalidArg` for a patch the engine refuses. Pure: it reads nothing\n * but its arguments.\n */\nexport function pdfResolveAnnotationPatch(\n  current: Annotation<PdfCoordinates>,\n  patch: AnnotationPatch<PdfCoordinates>,\n  options: ResolveOptions = {},\n): AnnotationPatch<PdfCoordinates> {\n  const prepared = pdfPrepareAnnotationPatch(current, patch);\n  assertAnnotationPatch(current, prepared);\n  return pdfDeriveAnnotationPatch(current, prepared, options);\n}\n\nfunction invalidWrite(error: z.ZodError, where: string): EngineError {\n  const issue = error.issues[0]!;\n  const field = issue.path.join('.');\n  return new EngineError(\n    EngineErrorCode.InvalidArg,\n    `${where}${field ? ` field '${field}'` : ''}: ${issue.message}`,\n    { details: field ? { field } : {} },\n  );\n}\n","/**\n * What an annotation import creates and leaves out, decided before its first write: each item\n * checked against its kind's create schema. Built with zod, so it runs where the engine does,\n * from `@embedpdf/engine-core/validation`; the facts an import commits are in\n * `annotationImport.ts`.\n */\nimport type { AnnotationBundle } from './AnnotationBundle';\nimport type { AnnotationDropReason, AnnotationImportDrop } from './annotationImport';\nimport { bundlePageMapping, type BundleImportPages, type BundleImportTarget } from './bundle';\nimport { mapPageRefs, pageRefsIn } from './pageRefs';\nimport {\n  AnnotationDraftSchema,\n  declarationOf,\n  type AnnotationDraft,\n  type Annotation,\n} from '../annotation/kinds';\nimport type { KindFields } from '../annotation/declaration';\nimport type { AnnotationReplyType } from '../annotation/primitives';\nimport type { PdfActionTree } from '../dto/PdfAction';\nimport { EngineError } from '../errors/EngineError';\nimport { EngineErrorCode } from '../errors/EngineErrorCode';\nimport { annotationKey } from '../identity/annotationKey';\nimport type { AnnotationRef } from '../identity/AnnotationRef';\nimport { encodePageKey, type PageRef } from '../identity/PageRef';\n\n/** One annotation an import creates. */\nexport interface PlannedAnnotation {\n  /** Its item in the bundle. */\n  readonly item: number;\n  /** The page it goes on. */\n  readonly page: PageRef;\n  /** What `create` writes: the item's data, its pages mapped, without its links and dropped fields. */\n  readonly draft: AnnotationDraft;\n  /** The annotation it replies to, by its place in `creates`. */\n  readonly replyTo?: { readonly planned: number; readonly type: AnnotationReplyType };\n  /** For a popup: the annotation it shows, by its place in `creates`. */\n  readonly parent?: number;\n}\n\nexport interface AnnotationImportPlan {\n  /** In bundle order. */\n  readonly creates: readonly PlannedAnnotation[];\n  readonly dropped: readonly AnnotationImportDrop[];\n}\n\n/**\n * What an import of `bundle` into the `target` pages creates, and what it\n * leaves out. Nothing here touches a document, so an import refuses before\n * its first write:\n *\n * - `InvalidArg` when an item's data isn't valid for its kind, or when a\n *   page an item is on or points at maps to no target page (naming them);\n * - `NotFound` when a page list maps to a page the target doesn't have.\n *\n * Unsupported items and unresolved relationships are left out in this order:\n *\n * 1. an item of an unsupported kind, and a form field's widget; a field\n *    marker leaves out only that field;\n * 2. an item whose `reply.to` or `parent` is no item of the bundle on the\n *    same target page (`parent-missing`);\n * 3. an item whose name is used on its target page, or by an earlier item\n *    going to the same page (`name-conflict`);\n * 4. then, until nothing changes, an item whose `reply.to` or `parent` was\n *    left out (`parent-dropped`), so a whole branch goes together.\n *\n * `nameTaken(page, nm)` answers for the target page as it is before the import.\n */\nexport function planAnnotationImport(input: {\n  readonly bundle: Pick<AnnotationBundle, 'pages' | 'items'>;\n  readonly pages?: BundleImportPages;\n  readonly target: readonly BundleImportTarget[];\n  readonly nameTaken: (page: PageRef, nm: string) => boolean;\n}): AnnotationImportPlan {\n  const { bundle, target, nameTaken } = input;\n  const items = bundle.items.map((item) => item.data);\n  const mapPage = bundlePageMapping({\n    bundlePages: bundle.pages,\n    pages: input.pages ?? 'same',\n    target,\n    named: items.flatMap(pagesNamedBy),\n  });\n\n  const drops = new Map<number, AnnotationDropReason>();\n  const fieldDrops = new Map<number, Array<{ field: string; reason: AnnotationDropReason }>>();\n  const drafts = new Map<number, AnnotationDraft>();\n  items.forEach((data, index) => {\n    if (data.subtype === 'unsupported') {\n      drops.set(index, 'unsupported-kind');\n      return;\n    }\n    if (data.subtype === 'widget') {\n      drops.set(index, 'widget');\n      return;\n    }\n    // A popup shows another annotation; one that names none can't be made.\n    if (data.subtype === 'popup' && data.parent === null) {\n      drops.set(index, 'parent-missing');\n      return;\n    }\n    const unwritable = unwritableValuesOf(data);\n    if (unwritable === 'item') {\n      drops.set(index, 'unsupported-value');\n      return;\n    }\n    const markers = [...fieldMarkersOf(data), ...unwritable];\n    if (markers.length > 0) fieldDrops.set(index, markers);\n    drafts.set(index, draftOf(data, markers, mapPage, index));\n  });\n\n  const byKey = new Map<string, number>();\n  items.forEach((data, index) => {\n    const key = annotationKey(data.ref);\n    if (!byKey.has(key)) byKey.set(key, index);\n  });\n  // A reply and a popup are on their parent's page (ISO 32000-2 §12.5.6.2),\n  // so a link finds its target only there.\n  const pageOf = (index: number) => encodePageKey(mapPage(items[index]!.ref.page));\n  const resolve = (ref: AnnotationRef, from: number) => {\n    const found = byKey.get(annotationKey(ref));\n    return found !== undefined && pageOf(found) === pageOf(from) ? found : undefined;\n  };\n  const linksOf = (data: Annotation) =>\n    [data.reply?.to, data.subtype === 'popup' ? data.parent : null].filter(\n      (ref): ref is AnnotationRef => ref != null,\n    );\n\n  items.forEach((data, index) => {\n    if (drops.has(index)) return;\n    if (linksOf(data).some((ref) => resolve(ref, index) === undefined)) {\n      drops.set(index, 'parent-missing');\n    }\n  });\n\n  const popupOf = new Map<number, number>();\n  items.forEach((data, index) => {\n    if (drops.has(index) || data.subtype !== 'popup' || !data.parent) return;\n    const parent = resolve(data.parent, index)!;\n    if (popupOf.has(parent)) drops.set(index, 'popup-taken');\n    else popupOf.set(parent, index);\n  });\n\n  const claimed = new Set<string>();\n  items.forEach((data, index) => {\n    if (drops.has(index) || !data.nm) return;\n    const page = mapPage(data.ref.page);\n    const claim = `${encodePageKey(page)}\\u0000${data.nm}`;\n    if (claimed.has(claim) || nameTaken(page, data.nm)) drops.set(index, 'name-conflict');\n    else claimed.add(claim);\n  });\n\n  for (let changed = true; changed; ) {\n    changed = false;\n    items.forEach((data, index) => {\n      if (drops.has(index)) return;\n      if (linksOf(data).some((ref) => drops.has(resolve(ref, index)!))) {\n        drops.set(index, 'parent-dropped');\n        changed = true;\n      }\n    });\n  }\n\n  const planned = new Map<number, number>();\n  items.forEach((_data, index) => {\n    if (!drops.has(index)) planned.set(index, planned.size);\n  });\n  const creates: PlannedAnnotation[] = [...planned.keys()].map((index) => {\n    const data = items[index]!;\n    const replyTo = data.reply ? planned.get(resolve(data.reply.to, index)!) : undefined;\n    const parent =\n      data.subtype === 'popup' && data.parent\n        ? planned.get(resolve(data.parent, index)!)\n        : undefined;\n    return {\n      item: index,\n      page: mapPage(data.ref.page),\n      draft: drafts.get(index)!,\n      ...(replyTo !== undefined ? { replyTo: { planned: replyTo, type: data.reply!.type } } : {}),\n      ...(parent !== undefined ? { parent } : {}),\n    };\n  });\n\n  const dropped: AnnotationImportDrop[] = [];\n  items.forEach((data, index) => {\n    const reason = drops.get(index);\n    if (reason) dropped.push({ ref: data.ref, reason });\n    else for (const drop of fieldDrops.get(index) ?? []) dropped.push({ ref: data.ref, ...drop });\n  });\n  return { creates, dropped };\n}\n\n/**\n * The pages an item is on or points at, apart from its links to other\n * annotations (`reply.to`, `parent`, `popup`), which resolve in the bundle.\n */\nfunction pagesNamedBy(data: Annotation): PageRef[] {\n  const { ref, reply: _reply, popup: _popup, ...rest } = data;\n  const fields = { ...rest } as Record<string, unknown>;\n  if (data.subtype === 'popup') delete fields.parent;\n  return [ref.page, ...pageRefsIn(fields)];\n}\n\n/** The fields of `data` that are markers for something the engine can't write. */\nfunction fieldMarkersOf(data: Annotation): Array<{ field: string; reason: AnnotationDropReason }> {\n  const markers: Array<{ field: string; reason: AnnotationDropReason }> = [];\n  const measure = (data as { measure?: { subtype?: unknown } | null }).measure;\n  if (measure?.subtype === 'geospatial') markers.push({ field: 'measure', reason: 'geospatial' });\n  if (measure?.subtype === 'unknown') markers.push({ field: 'measure', reason: 'unknown-measure' });\n  const target = data.subtype === 'link' ? data.target : null;\n  const carriedTarget = !!target && isWritableLinkTarget(target);\n  if (target && !carriedTarget) markers.push({ field: 'target', reason: 'unsupported-action' });\n  // `actions` reads `/A` and `/AA`, and no write takes it. A copy has only\n  // the `/A` a link's target writes: one go-to or URI action, without a\n  // chain or an `/IsMap`. A target a write can't make is reported above.\n  const { actions } = data;\n  const lost = Object.entries(actions ?? {}).some(([trigger, tree]) =>\n    data.subtype !== 'link' || trigger !== 'activate' ? true : carriedTarget && !writtenAsIs(tree),\n  );\n  if (lost) markers.push({ field: 'actions', reason: 'unsupported-action' });\n  return markers;\n}\n\n/**\n * The values `data` reads that a write can't make (a `readBack()` field's\n * read-only values), each left out; `'item'` when one is a field every\n * create needs. A link's target is reported by {@link fieldMarkersOf}.\n */\nfunction unwritableValuesOf(\n  data: Annotation,\n): Array<{ field: string; reason: AnnotationDropReason }> | 'item' {\n  const unwritable: Array<{ field: string; reason: AnnotationDropReason }> = [];\n  const declaration = declarationOf(data.subtype);\n  for (const [name, spec] of Object.entries(declaration?.fields ?? {})) {\n    const { owner, readBack, required } = spec.traits;\n    if (owner !== 'data' || !readBack || name === 'target') continue;\n    const value = (data as unknown as Record<string, unknown>)[name];\n    if (value == null || spec.write.safeParse(value).success) continue;\n    if (required) return 'item';\n    unwritable.push({ field: name, reason: 'unsupported-value' });\n  }\n  return unwritable;\n}\n\n/** Whether a link's `/A` is what writing its target writes again. */\nfunction writtenAsIs<Destination>(tree: PdfActionTree<Destination> | undefined): boolean {\n  const root = tree?.root;\n  if (!tree || tree.incomplete || !root || root.next.length > 0) return false;\n  return !(root.type === 'uri' && root.isMap);\n}\n\n/** Whether a write can make a link's target; the others read as markers. */\nfunction isWritableLinkTarget(target: { kind: string; name?: string }): boolean {\n  return target.kind === 'named'\n    ? STANDARD_NAMED_ACTIONS.has(target.name ?? '')\n    : target.kind === 'goto' || target.kind === 'uri';\n}\n\nconst STANDARD_NAMED_ACTIONS: ReadonlySet<string> = new Set([\n  'NextPage',\n  'PrevPage',\n  'FirstPage',\n  'LastPage',\n]);\n\n/** The create an item becomes, checked against its kind's create schema. */\nfunction draftOf(\n  data: Annotation,\n  markers: ReadonlyArray<{ field: string }>,\n  mapPage: (page: PageRef) => PageRef,\n  index: number,\n): AnnotationDraft {\n  const fields = { ...data } as Record<string, unknown>;\n  delete fields.reply;\n  // Left out, the field is not written: `null` where a write takes it,\n  // else the kind's default.\n  const declared: KindFields = declarationOf(data.subtype)?.fields ?? {};\n  for (const { field } of markers) {\n    if (declared[field]?.traits.writeNullable) fields[field] = null;\n    else delete fields[field];\n  }\n  // Checked with the popup's `parent`, which the import then links itself.\n  const checked = AnnotationDraftSchema.safeParse(fields);\n  if (data.subtype === 'popup') delete fields.parent;\n  if (!checked.success) {\n    const issue = checked.error.issues[0]!;\n    const path = issue.path.join('.');\n    throw new EngineError(\n      EngineErrorCode.InvalidArg,\n      `import: item ${index}${path ? ` field '${path}'` : ''}: ${issue.message}`,\n      { details: { item: index, ...(path ? { field: path } : {}) } },\n    );\n  }\n  // The item's own data, not the schema's output, so nothing a read carries\n  // is reshaped on its way back in.\n  return mapPageRefs(fields, mapPage) as AnnotationDraft;\n}\n","/**\n * What a form import writes and leaves out, decided before its first write: a design import's\n * fields checked against the create schema, a values import's values matched to the form's\n * fields. Built with zod, so it runs where the engine does, from\n * `@embedpdf/engine-core/validation`; the facts an import commits are in `formImport.ts`.\n */\nimport { bundlePageMapping, type BundleImportPages, type BundleImportTarget } from './bundle';\nimport type { FormBundle } from './FormBundle';\nimport { fieldMatches } from './formExport';\nimport {\n  WIDGET_FLAG_NAMES,\n  type FormImportDrop,\n  type FormImportDropReason,\n  type FormValuesImportDrop,\n  type FormValuesImportDropReason,\n  type WidgetFlags,\n} from './formImport';\nimport { mapPageRefs, pageRefsIn } from './pageRefs';\nimport type { WidgetAnnotation } from '../annotation/kinds/widget';\nimport {\n  actionWriteOf,\n  fieldScriptOf,\n  needsScriptRight,\n  WIDGET_ACTION_EVENTS,\n  type FieldActionsPatch,\n  type FieldScriptEvent,\n  type WidgetActionsPatch,\n} from '../dto/PdfAction';\nimport { EngineError } from '../errors/EngineError';\nimport { EngineErrorCode } from '../errors/EngineErrorCode';\nimport type { FormFieldDraft, WidgetPlacement } from '../forms/draft';\nimport type { FormFieldDTO, FormFieldFamily } from '../forms/field';\nimport { FormFieldDraftSchema } from '../forms/schema';\nimport { fieldValueOf, type FormFieldValue } from '../forms/value';\nimport { annotationKey } from '../identity/annotationKey';\nimport { encodeFieldRefKey, type FormFieldRef } from '../identity/FormFieldRef';\nimport type { PageRef } from '../identity/PageRef';\n\n/** One field a design import creates. */\nexport interface PlannedFormField {\n  /** Its row in the bundle. */\n  readonly field: number;\n  /** What `create` writes: the field's settings, scripts and widgets, their pages mapped. */\n  readonly draft: FormFieldDraft;\n  /** Each widget's row in the bundle, in `draft.widgets` order. */\n  readonly widgets: readonly number[];\n  /** Each widget's flags, in `draft.widgets` order. */\n  readonly flags: readonly WidgetFlags[];\n  /** The value it gets; absent when the import writes none. */\n  readonly value?: FormFieldValue;\n}\n\nexport interface FormImportPlan {\n  /** In bundle order. */\n  readonly creates: readonly PlannedFormField[];\n  /** The calculation order among the creates, by their place in `creates`, as the bundle has it. */\n  readonly calculationOrder: readonly number[];\n  readonly dropped: readonly FormImportDrop[];\n}\n\n/**\n * What a design import of `bundle` into the `target` pages creates, and what\n * it leaves out. Nothing here touches a document, so an import refuses\n * before its first write:\n *\n * - `InvalidArg` when a field's data isn't valid for its family, or when a\n *   page a widget is on or points at maps to no target page;\n * - `NotFound` when a page list maps to a page the target doesn't have.\n *\n * Left out, in bundle order: a field of an unknown family, a field whose\n * name is taken (`nameTaken`, for the document as it is before the\n * import), a widget whose field isn't in the bundle, and each action that\n * is a script, a submit or a link when `mayScript` is false\n * (`doc.forms.script`), or that a write can't make. Each field keeps every\n * widget it has. With `values`, each field gets the value the bundle holds.\n */\nexport function planFormImport(input: {\n  readonly bundle: Pick<FormBundle, 'pages' | 'fields' | 'widgets' | 'calculationOrder'>;\n  readonly pages?: BundleImportPages;\n  readonly target: readonly BundleImportTarget[];\n  readonly nameTaken: (name: string) => boolean;\n  readonly mayScript: boolean;\n  readonly values: boolean;\n}): FormImportPlan {\n  const { bundle, mayScript } = input;\n  const mapPage = bundlePageMapping({\n    bundlePages: bundle.pages,\n    pages: input.pages ?? 'same',\n    target: input.target,\n    named: bundle.widgets.flatMap((row) => pageRefsIn(row.data)),\n  });\n\n  const rowByKey = new Map(\n    bundle.widgets.map((row, index) => [annotationKey(row.data.ref), index]),\n  );\n  const owned = new Set<number>();\n  const dropped: FormImportDrop[] = [];\n  const claimed = new Set<string>();\n  const creates: PlannedFormField[] = [];\n\n  bundle.fields.forEach(({ data: field }, index) => {\n    const rows = field.widgets.flatMap((widget) => {\n      const row = widget.ref ? rowByKey.get(annotationKey(widget.ref)) : undefined;\n      return row === undefined ? [] : [row];\n    });\n    for (const row of rows) owned.add(row);\n    if (field.family === 'unknown') {\n      dropped.push({ ref: field.ref, reason: 'unsupported-family' });\n      return;\n    }\n    if (claimed.has(field.name) || input.nameTaken(field.name)) {\n      dropped.push({ ref: field.ref, reason: 'name-conflict' });\n      return;\n    }\n    claimed.add(field.name);\n    const actions = fieldActionsOf(field, mayScript, dropped);\n    const placements = rows.map((row) =>\n      placementOf(field, bundle.widgets[row]!.data, mapPage, mayScript, dropped),\n    );\n    const draft = draftOf(field, actions, placements, index);\n    const value = input.values && holdsValue(field) ? fieldValueOf(field) : null;\n    creates.push({\n      field: index,\n      draft,\n      widgets: rows,\n      flags: rows.map((row) => flagsOf(bundle.widgets[row]!.data)),\n      ...(value ? { value } : {}),\n    });\n  });\n\n  bundle.widgets.forEach((row, index) => {\n    if (!owned.has(index)) {\n      dropped.push({ ref: row.data.field, widget: row.data.ref, reason: 'no-field' });\n    }\n  });\n\n  // The order the bundle gives the fields that kept their calculate script.\n  const calculationOrder = bundle.calculationOrder.flatMap((ref) => {\n    const at = creates.findIndex(\n      (create) =>\n        encodeFieldRefKey(bundle.fields[create.field]!.data.ref) === encodeFieldRefKey(ref) &&\n        create.draft.actions?.calculate,\n    );\n    return at < 0 ? [] : [at];\n  });\n  return { creates, calculationOrder, dropped };\n}\n\n/** A field of the document a values import fills. */\nexport interface FormValuesImportTarget {\n  readonly ref: FormFieldRef;\n  readonly name: string;\n  readonly family: FormFieldFamily;\n}\n\n/** One value a values import writes. */\nexport interface PlannedValueWrite<T extends FormValuesImportTarget = FormValuesImportTarget> {\n  /** Its field's row in the bundle. */\n  readonly field: number;\n  /** The document's field of that name. */\n  readonly target: T;\n  readonly value: FormFieldValue;\n}\n\n/**\n * What a values import of `bundle` writes into a form whose fields are\n * `target`: each field the bundle holds a value for gets it, matched by full\n * name. Left out, in bundle order: a field the document doesn't have\n * (`no-field`), one of another family (`wrong-family`), and one `refusal`\n * names a reason for: a value the field can't take, a field a signature\n * locked, a field the session may not fill in. So everything is decided\n * before the first write.\n */\nexport function planFormValuesImport<T extends FormValuesImportTarget>(input: {\n  readonly bundle: Pick<FormBundle, 'fields'>;\n  readonly target: readonly T[];\n  readonly refusal?: (\n    target: T,\n    value: FormFieldValue,\n  ) => Extract<\n    FormValuesImportDropReason,\n    'value-not-allowed' | 'locked' | 'fill-not-allowed'\n  > | null;\n}): {\n  readonly writes: readonly PlannedValueWrite<T>[];\n  readonly dropped: readonly FormValuesImportDrop[];\n} {\n  const writes: PlannedValueWrite<T>[] = [];\n  const dropped: FormValuesImportDrop[] = [];\n  input.bundle.fields.forEach(({ data: field }, index) => {\n    const value = holdsValue(field) ? fieldValueOf(field) : null;\n    if (!value) return;\n    const target = input.target.find((candidate) =>\n      fieldMatches(candidate, { kind: 'fqn', name: field.name }),\n    );\n    if (!target) {\n      dropped.push({ ref: field.ref, reason: 'no-field' });\n    } else if (target.family !== field.family) {\n      dropped.push({ ref: field.ref, reason: 'wrong-family' });\n    } else {\n      const refused = input.refusal?.(target, value);\n      if (refused) dropped.push({ ref: field.ref, reason: refused });\n      else writes.push({ field: index, target, value });\n    }\n  });\n  return { writes, dropped };\n}\n\n/** Whether a field read holds a value a write can set. */\nfunction holdsValue(field: FormFieldDTO): boolean {\n  return field.valueEntry.kind === 'scalar' || field.valueEntry.kind === 'array';\n}\n\n/** A field's scripts as a create writes them; each left out is reported. */\nfunction fieldActionsOf(\n  field: FormFieldDTO,\n  mayScript: boolean,\n  dropped: FormImportDrop[],\n): FieldActionsPatch {\n  const actions: FieldActionsPatch = {};\n  for (const [event, tree] of Object.entries(field.actions ?? {}) as [\n    FieldScriptEvent,\n    NonNullable<FormFieldDTO['actions']>[FieldScriptEvent],\n  ][]) {\n    if (!tree) continue;\n    const script = fieldScriptOf(tree);\n    const member = `actions.${event}`;\n    if (!script) dropped.push({ ref: field.ref, field: member, reason: 'unsupported-action' });\n    else if (!mayScript)\n      dropped.push({ ref: field.ref, field: member, reason: 'script-not-allowed' });\n    else actions[event] = script;\n  }\n  return actions;\n}\n\n/** A widget row as a create places it: on its mapped page, with its look and actions. */\nfunction placementOf(\n  field: FormFieldDTO,\n  row: WidgetAnnotation,\n  mapPage: (page: PageRef) => PageRef,\n  mayScript: boolean,\n  dropped: FormImportDrop[],\n): WidgetPlacement {\n  const actions: WidgetActionsPatch = {};\n  for (const event of WIDGET_ACTION_EVENTS) {\n    const tree = row.actions?.[event];\n    if (!tree) continue;\n    const write = actionWriteOf(tree);\n    const drop = (reason: FormImportDropReason) =>\n      dropped.push({ ref: field.ref, widget: row.ref, field: `actions.${event}`, reason });\n    if (!write) drop('unsupported-action');\n    else if (!mayScript && needsScriptRight(write)) drop('script-not-allowed');\n    else actions[event] = mapPageRefs(write, mapPage);\n  }\n  const toggle =\n    field.family === 'checkbox' || field.family === 'radio'\n      ? field.widgets.find(\n          (widget) => widget.ref && annotationKey(widget.ref) === annotationKey(row.ref),\n        )\n      : undefined;\n  const look = {\n    color: row.color,\n    interiorColor: row.interiorColor,\n    fontFamily: row.fontFamily,\n    fontSize: row.fontSize,\n    fontColor: row.fontColor,\n    caption: field.family === 'pushbutton' ? row.caption : null,\n  };\n  return {\n    page: mapPage(row.page),\n    rect: row.rect,\n    ...(row.rotation ? { rotation: row.rotation } : {}),\n    strokeWidth: row.strokeWidth,\n    borderStyle: row.borderStyle,\n    textAlign: row.textAlign,\n    // A new widget has none of these: only what the row has is written.\n    ...Object.fromEntries(Object.entries(look).filter(([, value]) => value != null)),\n    ...(toggle && 'exportValue' in toggle ? { exportValue: toggle.exportValue } : {}),\n    ...(Object.keys(actions).length > 0 ? { actions } : {}),\n  };\n}\n\nfunction flagsOf(row: WidgetAnnotation): WidgetFlags {\n  return Object.fromEntries(WIDGET_FLAG_NAMES.map((name) => [name, row[name]])) as WidgetFlags;\n}\n\n/** The create a field row becomes, checked against the create schema. */\nfunction draftOf(\n  field: FormFieldDTO,\n  actions: FieldActionsPatch,\n  widgets: WidgetPlacement[],\n  index: number,\n): FormFieldDraft {\n  const base = {\n    name: field.name,\n    readOnly: field.readOnly,\n    required: field.required,\n    noExport: field.noExport,\n    ...(field.alternateName !== null ? { alternateName: field.alternateName } : {}),\n    ...(field.mappingName !== null ? { mappingName: field.mappingName } : {}),\n    // The group the field was in; the import decides whether it keeps it.\n    ...(field.groupId !== null ? { groupId: field.groupId } : {}),\n    ...(Object.keys(actions).length > 0 ? { actions } : {}),\n    widgets,\n  };\n  const hasDefault = field.defaultValueEntry.kind !== 'none';\n  const options = (list: readonly { label: string; value: string }[]) =>\n    list.map(({ label, value }) => ({ label, value }));\n  let draft: FormFieldDraft;\n  switch (field.family) {\n    case 'text':\n      draft = {\n        ...base,\n        family: 'text',\n        ...(hasDefault ? { defaultValue: field.defaultValue } : {}),\n        ...(field.maxLength !== null ? { maxLength: field.maxLength } : {}),\n        multiline: field.multiline,\n        password: field.password,\n        comb: field.comb,\n      };\n      break;\n    case 'radio':\n      draft = {\n        ...base,\n        family: 'radio',\n        radiosInUnison: field.radiosInUnison,\n        noToggleToOff: field.noToggleToOff,\n      };\n      break;\n    case 'combobox':\n      draft = {\n        ...base,\n        family: 'combobox',\n        edit: field.edit,\n        options: options(field.options),\n        ...(hasDefault ? { defaultValue: field.defaultValue } : {}),\n      };\n      break;\n    case 'listbox':\n      draft = {\n        ...base,\n        family: 'listbox',\n        multiSelect: field.multiSelect,\n        options: options(field.options),\n        ...(hasDefault ? { defaultValue: field.defaultValue } : {}),\n      };\n      break;\n    case 'checkbox':\n    case 'pushbutton':\n    case 'signature':\n      draft = { ...base, family: field.family };\n      break;\n    default:\n      throw new EngineError(EngineErrorCode.InvalidArg, `import: field ${index} has no family`);\n  }\n  const checked = FormFieldDraftSchema.safeParse(draft);\n  if (!checked.success) {\n    const issue = checked.error.issues[0]!;\n    const path = issue.path.join('.');\n    throw new EngineError(\n      EngineErrorCode.InvalidArg,\n      `import: field ${index}${path ? ` member '${path}'` : ''}: ${issue.message}`,\n      { details: { item: index, ...(path ? { field: path } : {}) } },\n    );\n  }\n  return draft;\n}\n"],"mappings":"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"}

package/dist/validation.d.cts

@@ -0,0 +1,174 @@
+import { Aa as FormFieldValue, Hc as FormValuesImportDropReason, Ic as FormImportDrop, Js as ResolveOptions, Kc as WidgetFlags, Mg as PdfCoordinates, Mu as BundleImportTarget, Rl as AnnotationImportDrop, Tf as AnnotationReplyType, Vc as FormValuesImportDrop, Zg as FormFieldRef, bs as AnnotationDraft, ju as BundleImportPages, qs as DraftResolveOptions, uv as PageRef, vg as FormFieldFamily, vl as FormBundle, vo as FormFieldDraft, vs as Annotation, vu as AnnotationBundle, xs as AnnotationPatch } from "./AnnotationList-CkijRHet.cjs";
+//#region src/annotation/checkWrite.d.ts
+/**
+ * A prepared create's data checked against its kind's schema. The caller
+ * writes its own data, not the schema's output, so nothing is reshaped on its
+ * way in.
+ */
+declare function assertAnnotationDraft(draft: AnnotationDraft<PdfCoordinates>, options?: {
+  /**
+   * Link fields the caller has taken out of the draft and links itself (a
+   * change set's `reply` and popup `parent`); they aren't checked here.
+   */
+  linked?: readonly string[];
+}): void;
+/**
+ * A prepared update's data (`pdfPrepareAnnotationPatch`) checked against the
+ * kind of `current`. A `readBack()` value still in it is a change, as
+ * preparation drops one sent back as it reads, so one a write can't make is
+ * refused; the rest is checked against the kind's update schema.
+ */
+declare function assertAnnotationPatch(current: Annotation<PdfCoordinates>, prepared: AnnotationPatch<PdfCoordinates>): void;
+/**
+ * The draft the engine writes for `draft`, in the file's coordinates:
+ * prepared (`pdfPrepareAnnotationDraft`), checked against its kind, and
+ * every field that follows from it stated (`pdfDeriveAnnotationDraft`). A
+ * viewer predicts the same without schema validation
+ * (`pdfPredictAnnotationDraft`).
+ *
+ * Throws `InvalidArg` for a draft the engine refuses. Pure: it reads nothing
+ * but its arguments.
+ */
+declare function pdfResolveAnnotationDraft(draft: AnnotationDraft<PdfCoordinates>, options?: DraftResolveOptions): AnnotationDraft<PdfCoordinates>;
+/**
+ * The patch the engine writes for `patch` on `current`, in the file's
+ * coordinates: prepared (`pdfPrepareAnnotationPatch`), checked against its
+ * kind (`assertAnnotationPatch`), and every field that follows from it
+ * stated (`pdfDeriveAnnotationPatch`). A viewer predicts the same without
+ * schema validation (`pdfPredictAnnotationPatch`).
+ *
+ * Throws `InvalidArg` for a patch the engine refuses. Pure: it reads nothing
+ * but its arguments.
+ */
+declare function pdfResolveAnnotationPatch(current: Annotation<PdfCoordinates>, patch: AnnotationPatch<PdfCoordinates>, options?: ResolveOptions): AnnotationPatch<PdfCoordinates>;
+//#endregion
+//#region src/transfer/planAnnotationImport.d.ts
+/** One annotation an import creates. */
+interface PlannedAnnotation {
+  /** Its item in the bundle. */
+  readonly item: number;
+  /** The page it goes on. */
+  readonly page: PageRef;
+  /** What `create` writes: the item's data, its pages mapped, without its links and dropped fields. */
+  readonly draft: AnnotationDraft;
+  /** The annotation it replies to, by its place in `creates`. */
+  readonly replyTo?: {
+    readonly planned: number;
+    readonly type: AnnotationReplyType;
+  };
+  /** For a popup: the annotation it shows, by its place in `creates`. */
+  readonly parent?: number;
+}
+interface AnnotationImportPlan {
+  /** In bundle order. */
+  readonly creates: readonly PlannedAnnotation[];
+  readonly dropped: readonly AnnotationImportDrop[];
+}
+/**
+ * What an import of `bundle` into the `target` pages creates, and what it
+ * leaves out. Nothing here touches a document, so an import refuses before
+ * its first write:
+ *
+ * - `InvalidArg` when an item's data isn't valid for its kind, or when a
+ *   page an item is on or points at maps to no target page (naming them);
+ * - `NotFound` when a page list maps to a page the target doesn't have.
+ *
+ * Unsupported items and unresolved relationships are left out in this order:
+ *
+ * 1. an item of an unsupported kind, and a form field's widget; a field
+ *    marker leaves out only that field;
+ * 2. an item whose `reply.to` or `parent` is no item of the bundle on the
+ *    same target page (`parent-missing`);
+ * 3. an item whose name is used on its target page, or by an earlier item
+ *    going to the same page (`name-conflict`);
+ * 4. then, until nothing changes, an item whose `reply.to` or `parent` was
+ *    left out (`parent-dropped`), so a whole branch goes together.
+ *
+ * `nameTaken(page, nm)` answers for the target page as it is before the import.
+ */
+declare function planAnnotationImport(input: {
+  readonly bundle: Pick<AnnotationBundle, 'pages' | 'items'>;
+  readonly pages?: BundleImportPages;
+  readonly target: readonly BundleImportTarget[];
+  readonly nameTaken: (page: PageRef, nm: string) => boolean;
+}): AnnotationImportPlan;
+//#endregion
+//#region src/transfer/planFormImport.d.ts
+/** One field a design import creates. */
+interface PlannedFormField {
+  /** Its row in the bundle. */
+  readonly field: number;
+  /** What `create` writes: the field's settings, scripts and widgets, their pages mapped. */
+  readonly draft: FormFieldDraft;
+  /** Each widget's row in the bundle, in `draft.widgets` order. */
+  readonly widgets: readonly number[];
+  /** Each widget's flags, in `draft.widgets` order. */
+  readonly flags: readonly WidgetFlags[];
+  /** The value it gets; absent when the import writes none. */
+  readonly value?: FormFieldValue;
+}
+interface FormImportPlan {
+  /** In bundle order. */
+  readonly creates: readonly PlannedFormField[];
+  /** The calculation order among the creates, by their place in `creates`, as the bundle has it. */
+  readonly calculationOrder: readonly number[];
+  readonly dropped: readonly FormImportDrop[];
+}
+/**
+ * What a design import of `bundle` into the `target` pages creates, and what
+ * it leaves out. Nothing here touches a document, so an import refuses
+ * before its first write:
+ *
+ * - `InvalidArg` when a field's data isn't valid for its family, or when a
+ *   page a widget is on or points at maps to no target page;
+ * - `NotFound` when a page list maps to a page the target doesn't have.
+ *
+ * Left out, in bundle order: a field of an unknown family, a field whose
+ * name is taken (`nameTaken`, for the document as it is before the
+ * import), a widget whose field isn't in the bundle, and each action that
+ * is a script, a submit or a link when `mayScript` is false
+ * (`doc.forms.script`), or that a write can't make. Each field keeps every
+ * widget it has. With `values`, each field gets the value the bundle holds.
+ */
+declare function planFormImport(input: {
+  readonly bundle: Pick<FormBundle, 'pages' | 'fields' | 'widgets' | 'calculationOrder'>;
+  readonly pages?: BundleImportPages;
+  readonly target: readonly BundleImportTarget[];
+  readonly nameTaken: (name: string) => boolean;
+  readonly mayScript: boolean;
+  readonly values: boolean;
+}): FormImportPlan;
+/** A field of the document a values import fills. */
+interface FormValuesImportTarget {
+  readonly ref: FormFieldRef;
+  readonly name: string;
+  readonly family: FormFieldFamily;
+}
+/** One value a values import writes. */
+interface PlannedValueWrite<T extends FormValuesImportTarget = FormValuesImportTarget> {
+  /** Its field's row in the bundle. */
+  readonly field: number;
+  /** The document's field of that name. */
+  readonly target: T;
+  readonly value: FormFieldValue;
+}
+/**
+ * What a values import of `bundle` writes into a form whose fields are
+ * `target`: each field the bundle holds a value for gets it, matched by full
+ * name. Left out, in bundle order: a field the document doesn't have
+ * (`no-field`), one of another family (`wrong-family`), and one `refusal`
+ * names a reason for: a value the field can't take, a field a signature
+ * locked, a field the session may not fill in. So everything is decided
+ * before the first write.
+ */
+declare function planFormValuesImport<T extends FormValuesImportTarget>(input: {
+  readonly bundle: Pick<FormBundle, 'fields'>;
+  readonly target: readonly T[];
+  readonly refusal?: (target: T, value: FormFieldValue) => Extract<FormValuesImportDropReason, 'value-not-allowed' | 'locked' | 'fill-not-allowed'> | null;
+}): {
+  readonly writes: readonly PlannedValueWrite<T>[];
+  readonly dropped: readonly FormValuesImportDrop[];
+};
+//#endregion
+export { type AnnotationImportPlan, type FormImportPlan, type FormValuesImportTarget, type PlannedAnnotation, type PlannedFormField, type PlannedValueWrite, assertAnnotationDraft, assertAnnotationPatch, pdfResolveAnnotationDraft, pdfResolveAnnotationPatch, planAnnotationImport, planFormImport, planFormValuesImport };
+//# sourceMappingURL=validation.d.cts.map

package/dist/validation.d.ts

@@ -0,0 +1,174 @@
+import { Aa as FormFieldValue, Hc as FormValuesImportDropReason, Ic as FormImportDrop, Js as ResolveOptions, Kc as WidgetFlags, Mg as PdfCoordinates, Mu as BundleImportTarget, Rl as AnnotationImportDrop, Tf as AnnotationReplyType, Vc as FormValuesImportDrop, Zg as FormFieldRef, bs as AnnotationDraft, ju as BundleImportPages, qs as DraftResolveOptions, uv as PageRef, vg as FormFieldFamily, vl as FormBundle, vo as FormFieldDraft, vs as Annotation, vu as AnnotationBundle, xs as AnnotationPatch } from "./AnnotationList-CkijRHet.js";
+//#region src/annotation/checkWrite.d.ts
+/**
+ * A prepared create's data checked against its kind's schema. The caller
+ * writes its own data, not the schema's output, so nothing is reshaped on its
+ * way in.
+ */
+declare function assertAnnotationDraft(draft: AnnotationDraft<PdfCoordinates>, options?: {
+  /**
+   * Link fields the caller has taken out of the draft and links itself (a
+   * change set's `reply` and popup `parent`); they aren't checked here.
+   */
+  linked?: readonly string[];
+}): void;
+/**
+ * A prepared update's data (`pdfPrepareAnnotationPatch`) checked against the
+ * kind of `current`. A `readBack()` value still in it is a change, as
+ * preparation drops one sent back as it reads, so one a write can't make is
+ * refused; the rest is checked against the kind's update schema.
+ */
+declare function assertAnnotationPatch(current: Annotation<PdfCoordinates>, prepared: AnnotationPatch<PdfCoordinates>): void;
+/**
+ * The draft the engine writes for `draft`, in the file's coordinates:
+ * prepared (`pdfPrepareAnnotationDraft`), checked against its kind, and
+ * every field that follows from it stated (`pdfDeriveAnnotationDraft`). A
+ * viewer predicts the same without schema validation
+ * (`pdfPredictAnnotationDraft`).
+ *
+ * Throws `InvalidArg` for a draft the engine refuses. Pure: it reads nothing
+ * but its arguments.
+ */
+declare function pdfResolveAnnotationDraft(draft: AnnotationDraft<PdfCoordinates>, options?: DraftResolveOptions): AnnotationDraft<PdfCoordinates>;
+/**
+ * The patch the engine writes for `patch` on `current`, in the file's
+ * coordinates: prepared (`pdfPrepareAnnotationPatch`), checked against its
+ * kind (`assertAnnotationPatch`), and every field that follows from it
+ * stated (`pdfDeriveAnnotationPatch`). A viewer predicts the same without
+ * schema validation (`pdfPredictAnnotationPatch`).
+ *
+ * Throws `InvalidArg` for a patch the engine refuses. Pure: it reads nothing
+ * but its arguments.
+ */
+declare function pdfResolveAnnotationPatch(current: Annotation<PdfCoordinates>, patch: AnnotationPatch<PdfCoordinates>, options?: ResolveOptions): AnnotationPatch<PdfCoordinates>;
+//#endregion
+//#region src/transfer/planAnnotationImport.d.ts
+/** One annotation an import creates. */
+interface PlannedAnnotation {
+  /** Its item in the bundle. */
+  readonly item: number;
+  /** The page it goes on. */
+  readonly page: PageRef;
+  /** What `create` writes: the item's data, its pages mapped, without its links and dropped fields. */
+  readonly draft: AnnotationDraft;
+  /** The annotation it replies to, by its place in `creates`. */
+  readonly replyTo?: {
+    readonly planned: number;
+    readonly type: AnnotationReplyType;
+  };
+  /** For a popup: the annotation it shows, by its place in `creates`. */
+  readonly parent?: number;
+}
+interface AnnotationImportPlan {
+  /** In bundle order. */
+  readonly creates: readonly PlannedAnnotation[];
+  readonly dropped: readonly AnnotationImportDrop[];
+}
+/**
+ * What an import of `bundle` into the `target` pages creates, and what it
+ * leaves out. Nothing here touches a document, so an import refuses before
+ * its first write:
+ *
+ * - `InvalidArg` when an item's data isn't valid for its kind, or when a
+ *   page an item is on or points at maps to no target page (naming them);
+ * - `NotFound` when a page list maps to a page the target doesn't have.
+ *
+ * Unsupported items and unresolved relationships are left out in this order:
+ *
+ * 1. an item of an unsupported kind, and a form field's widget; a field
+ *    marker leaves out only that field;
+ * 2. an item whose `reply.to` or `parent` is no item of the bundle on the
+ *    same target page (`parent-missing`);
+ * 3. an item whose name is used on its target page, or by an earlier item
+ *    going to the same page (`name-conflict`);
+ * 4. then, until nothing changes, an item whose `reply.to` or `parent` was
+ *    left out (`parent-dropped`), so a whole branch goes together.
+ *
+ * `nameTaken(page, nm)` answers for the target page as it is before the import.
+ */
+declare function planAnnotationImport(input: {
+  readonly bundle: Pick<AnnotationBundle, 'pages' | 'items'>;
+  readonly pages?: BundleImportPages;
+  readonly target: readonly BundleImportTarget[];
+  readonly nameTaken: (page: PageRef, nm: string) => boolean;
+}): AnnotationImportPlan;
+//#endregion
+//#region src/transfer/planFormImport.d.ts
+/** One field a design import creates. */
+interface PlannedFormField {
+  /** Its row in the bundle. */
+  readonly field: number;
+  /** What `create` writes: the field's settings, scripts and widgets, their pages mapped. */
+  readonly draft: FormFieldDraft;
+  /** Each widget's row in the bundle, in `draft.widgets` order. */
+  readonly widgets: readonly number[];
+  /** Each widget's flags, in `draft.widgets` order. */
+  readonly flags: readonly WidgetFlags[];
+  /** The value it gets; absent when the import writes none. */
+  readonly value?: FormFieldValue;
+}
+interface FormImportPlan {
+  /** In bundle order. */
+  readonly creates: readonly PlannedFormField[];
+  /** The calculation order among the creates, by their place in `creates`, as the bundle has it. */
+  readonly calculationOrder: readonly number[];
+  readonly dropped: readonly FormImportDrop[];
+}
+/**
+ * What a design import of `bundle` into the `target` pages creates, and what
+ * it leaves out. Nothing here touches a document, so an import refuses
+ * before its first write:
+ *
+ * - `InvalidArg` when a field's data isn't valid for its family, or when a
+ *   page a widget is on or points at maps to no target page;
+ * - `NotFound` when a page list maps to a page the target doesn't have.
+ *
+ * Left out, in bundle order: a field of an unknown family, a field whose
+ * name is taken (`nameTaken`, for the document as it is before the
+ * import), a widget whose field isn't in the bundle, and each action that
+ * is a script, a submit or a link when `mayScript` is false
+ * (`doc.forms.script`), or that a write can't make. Each field keeps every
+ * widget it has. With `values`, each field gets the value the bundle holds.
+ */
+declare function planFormImport(input: {
+  readonly bundle: Pick<FormBundle, 'pages' | 'fields' | 'widgets' | 'calculationOrder'>;
+  readonly pages?: BundleImportPages;
+  readonly target: readonly BundleImportTarget[];
+  readonly nameTaken: (name: string) => boolean;
+  readonly mayScript: boolean;
+  readonly values: boolean;
+}): FormImportPlan;
+/** A field of the document a values import fills. */
+interface FormValuesImportTarget {
+  readonly ref: FormFieldRef;
+  readonly name: string;
+  readonly family: FormFieldFamily;
+}
+/** One value a values import writes. */
+interface PlannedValueWrite<T extends FormValuesImportTarget = FormValuesImportTarget> {
+  /** Its field's row in the bundle. */
+  readonly field: number;
+  /** The document's field of that name. */
+  readonly target: T;
+  readonly value: FormFieldValue;
+}
+/**
+ * What a values import of `bundle` writes into a form whose fields are
+ * `target`: each field the bundle holds a value for gets it, matched by full
+ * name. Left out, in bundle order: a field the document doesn't have
+ * (`no-field`), one of another family (`wrong-family`), and one `refusal`
+ * names a reason for: a value the field can't take, a field a signature
+ * locked, a field the session may not fill in. So everything is decided
+ * before the first write.
+ */
+declare function planFormValuesImport<T extends FormValuesImportTarget>(input: {
+  readonly bundle: Pick<FormBundle, 'fields'>;
+  readonly target: readonly T[];
+  readonly refusal?: (target: T, value: FormFieldValue) => Extract<FormValuesImportDropReason, 'value-not-allowed' | 'locked' | 'fill-not-allowed'> | null;
+}): {
+  readonly writes: readonly PlannedValueWrite<T>[];
+  readonly dropped: readonly FormValuesImportDrop[];
+};
+//#endregion
+export { type AnnotationImportPlan, type FormImportPlan, type FormValuesImportTarget, type PlannedAnnotation, type PlannedFormField, type PlannedValueWrite, assertAnnotationDraft, assertAnnotationPatch, pdfResolveAnnotationDraft, pdfResolveAnnotationPatch, planAnnotationImport, planFormImport, planFormValuesImport };
+//# sourceMappingURL=validation.d.ts.map