annex

Define annex slots for supplementary documents that can be attached to a form. Annexes are predefined placeholders for supporting documents like IDs, contracts, or receipts.

Examples

Creating annexes

// Required document
const photoId = annex()
  .title('Photo ID')
  .description('Upload a government-issued photo ID')
  .required()
  .order(1)
  .build()

// Optional document
const proofOfAddress = annex()
  .title('Proof of Address')
  .description('Utility bill or bank statement')
  .build()

// Conditionally required (using logic expression)
const parentConsent = annex()
  .title('Parental Consent Form')
  .required('!isAdult')
  .visible('!isAdult')
  .build()

Adding annexes to forms

// Object pattern
const form = p.form({
  name: 'application',
  annexes: {
    photoId: { title: 'Photo ID', required: true },
    proofOfAddress: { title: 'Proof of Address' }
  },
  allowAdditionalAnnexes: true  // Allow additional ad-hoc attachments
})

// Builder pattern
const form = p.form()
  .name('application')
  .annex('photoId', annex().title('Photo ID').required().build())
  .annex('proofOfAddress', annex().title('Proof of Address').build())
  .allowAdditionalAnnexes(true)
  .build()

API

Object Pattern

Create annex definitions directly as objects:

const annexDef: FormAnnex = {
  title: 'Photo ID',
  description: 'Government-issued photo identification',
  required: true,
  visible: true,
  order: 1
}

Properties

title?: string

Display title for the annex slot

description?: string

Description of what document to attach

required?: boolean | string

Whether annex must be filled. Can be an expression.

visible?: boolean | string

Whether annex is visible. Can be an expression.

order?: number

Display order for rendering

Builder Pattern

Chain methods to build an annex incrementally:

All methods return FormAnnexBuilder and are chainable.

annex()

title: (value: string) => FormAnnexBuilder

Set display title

description: (value: string) => FormAnnexBuilder

Set description text

required: (value?: boolean | string) => FormAnnexBuilder

Mark as required (default: true). Accepts expression.

visible: (value?: boolean | string) => FormAnnexBuilder

Set visibility (default: true). Accepts expression.

order: (value: number) => FormAnnexBuilder

Set display order for rendering

from: (value: FormAnnex) => FormAnnexBuilder

Initialize from existing annex

build: () => FormAnnex

Build and validate

Static Methods

parse: (input: unknown) => FormAnnex

Parse unknown input (throws on error)

safeParse: (input: unknown) => Result<FormAnnex>

Parse unknown input (returns result object)

Conditional Annexes

Use defs for conditional requirements:

const form = p.form()
  .name('loan-application')
  .field('amount', field.number().label('Loan amount').build())
  .field('age', field.number().label('Applicant age').build())
  .def('isLargeAmount', 'fields.amount > 50000')
  .def('isMinor', 'fields.age < 18')
  .annex('financialStatements', annex()
    .title('Financial Statements')
    .description('Required for loans over $50,000')
    .required('isLargeAmount')
    .visible('isLargeAmount')
    .build())
  .annex('parentConsent', annex()
    .title('Parental Consent')
    .required('isMinor')
    .visible('isMinor')
    .build())
  .build()

Ad-hoc Annexes

Set allowAdditionalAnnexes: true on the form to permit additional attachments beyond predefined slots:

const form = p.form({
  name: 'application',
  annexes: {
    requiredDoc: { title: 'Required Document', required: true }
  },
  allowAdditionalAnnexes: true  // Users can attach additional documents
})

An additional annex value must still be an Attachment. Without allowAdditionalAnnexes: true, a payload with an undeclared annex key fails validation. The inferred payload type (InferFormPayload) follows the same rule for the object pattern and the builder.

form - Parent form artifact
Annex Schema

annex
Last updated on