Schema reference

abstract class Element {
  protected _children?: Element[]
  abstract getType(): string
  abstract toMeta(): Record<string, unknown>
  getChildren(): Element[] | undefined
}

import { Element } from '@pilotiq/pilotiq'

export class Stat extends Element {
  private constructor(private label: string, private value: string | number) { super() }
  static make(label: string, value: string | number) { return new Stat(label, value) }

  getType() { return 'stat' }
  toMeta() { return { type: 'stat', label: this.label, value: this.value } }
}

TextField.make('email')
  .label('Email address')
  .required()
  .placeholder('[email protected]')
  .hideFromTable()
  .showWhen(record => record.subscribed)
  .validate([email(), maxLength(120)])

.hideFromTable()
.hideFromCreate()
.hideFromEdit()
.hideFromView()

.showWhen(record => boolean)   // hide if returns false
.hideWhen(record => boolean)   // hide if returns true
.disabledWhen(record => boolean)

interface FieldMeta extends ElementMeta {
  type:         'field'
  fieldType:    'text' | 'textarea' | 'email' | 'number' | 'select' | 'toggle' | 'date' | 'slug'
  name:         string
  label:        string
  required:     boolean
  disabled:     boolean
  placeholder?: string
  rules?:       SerializedRule[]
  // subtypes append their own keys (e.g. maxLength, options, min/max/step)
}

type Validator = (value: unknown, ctx?: ValidatorContext) => string | null
                 & { serialized?: SerializedRule }

interface ValidatorContext { values?: Record<string, unknown>; record?: unknown }
interface SerializedRule    { rule: string; message?: string; [k: string]: unknown }

required(message?)
email(message?)
minLength(n, message?)
maxLength(n, message?)
min(n, message?)
max(n, message?)
pattern(regex, message?)

EmailField.make('email').required().validate(email())

import { makeValidator } from '@pilotiq/pilotiq'

const profanityFree = makeValidator(
  value => {
    if (typeof value !== 'string') return null
    return /badword/.test(value) ? 'Watch your language' : null
  },
  { rule: 'profanityFree', message: 'Watch your language' }, // optional
)

TextField.make('comment').validate(profanityFree)

import { unique } from '@pilotiq/pilotiq'

EmailField.make('email')
  .required()
  .validate(unique({ model: User, caseInsensitive: true }))

TextField.make('slug')
  .validate(unique({ model: Post }))                    // column = field name

TextField.make('name')
  .validate(unique({
    model: Project,
    where: ({ values }) => ({ tenantId: values.tenantId }),  // scoped uniqueness
    message: 'That project name is already taken',
  }))

const errors = await field.runValidators(value, { values, record })  // → string[]

import { validateSchema, isValid } from '@pilotiq/pilotiq'

const errors = await validateSchema(form.schema, submittedValues, currentRecord)
if (!isValid(errors)) { /* errors is { fieldName: string[] } */ }

Action.make('publish').label('Publish')
  .placement('inline')   // 'inline' | 'bulk' | 'row' | 'header'
  .icon('Send')
  .destructive(false)
  .confirm({ title: 'Publish article?', message: 'This goes public immediately.' })
  .handler(async ctx => { /* … */ })

// Link-style — renders <a href={url}>
Action.make('edit').label('Edit').href(`${basePath}/articles/${id}/edit`)

// Form-style — renders <form method="post" action={url}><button type="submit">
Action.make('delete').label('Delete')
  .destructive()
  .method('post')
  .action(`${basePath}/articles/${id}/delete`)
  .confirm('Delete this article?')

Form.make()
  .schema([
    TextField.make('title').required(),
    TextareaField.make('body'),
    Action.make('save').label('Save'),
  ])
  .validate(passwordsMatch)               // form-level validators (run after field-level)
  .mutateData(d => ({ ...d, slug: slugify(d.title) }))                  // both modes
  .mutateDataBeforeCreate(d => ({ ...d, createdBy: 'system' }))         // create-only
  .beforeSave(async (data, ctx) => { /* hooks */ })                     // both modes
  .beforeUpdate(async (data, ctx) => { /* update-only */ })
  .save(async (data, ctx) => prisma.article.create({ data }))           // shared persistence
  .handleCreate(async (data) => prisma.article.create({ data }))        // create-only override
  .handleUpdate(async (data, ctx) =>
    prisma.article.update({ where: { id: ctx.record.id }, data }))      // update-only override
  .afterSave(async (record, ctx) => { /* hooks */ })
  .redirectAfterSave(rec => `/admin/articles/${rec.id}/edit`)
  .savedNotification('Saved')               // string | Notification | NotificationMeta | fn | null
  .createdNotification('Created')           // create-mode override; falls back to savedNotification
  .loadRecord(async (id) => prisma.article.findUnique({ where: { id } }))
  .mutateFormDataBeforeFill((values, ctx) => values)  // edit-mode load path
  .fillFromRecord(record => ({ ...record }))          // optional — defaults to spread
  .mutateFormDataAfterFill((values, ctx) => values)

validateSchema(form.children, body)        // walks every Field, runs validators
  → form-level validators                  // cross-field rules; errors land under `_form`
  → mutateData(data, ctx)                  // both modes
  → mutateDataBeforeCreate / BeforeUpdate  // mode-specific
  → beforeSave(data, ctx)                  // both modes
  → beforeCreate / beforeUpdate            // mode-specific
  → handleCreate || handleUpdate || save   // persistence; mode override wins over save()
  → afterCreate / afterUpdate              // mode-specific
  → afterSave(record, ctx)                 // both modes
  → redirectAfterSave(record, ctx) → url

loadRecord(id, ctx)
  → mutateFormDataBeforeFill(values, ctx)  // edit-mode only
  → fillFromRecord(record)                 // defaults to { ...record }
  → mutateFormDataAfterFill(values, ctx)
  → form.withValues(...)

form.withValues(values)   // pre-fill inputs (edit mode, or after error)
form.withErrors(errors)   // shown next to each Field; `_form` becomes a top-of-form banner
form.action(url)          // form's POST URL; framework auto-sets to current route

interface FormMeta extends ElementMeta {
  type:    'form'
  formId:  string                                // auto-generated; multi-form pages use this
  method:  'get' | 'post' | 'put' | 'patch' | 'delete'
  action?: string
  values?: Record<string, unknown>
  errors?: { [fieldName: string]: string[]; _form?: string[] }
}

Table.make()
  .columns([
    Column.make('title').sortable().searchable(),
    Column.make('status'),
    Column.make('createdAt'),
  ])
  .defaultSort('createdAt', 'desc')
  .paginate(10)
  .records(async (ctx) => {
    const where = ctx.search ? { title: { contains: ctx.search } } : undefined
    const orderBy = ctx.sort ? { [ctx.sort.column]: ctx.sort.direction } : undefined
    return {
      rows:  await prisma.article.findMany({ where, orderBy, take: ctx.perPage, skip: (ctx.page - 1) * ctx.perPage }),
      total: await prisma.article.count({ where }),
    }
  })

interface TableContext {
  search?: string
  sort?:   { column: string; direction: 'asc' | 'desc' }
  page?:   number
  perPage?: number
}

interface TableMeta extends ElementMeta {
  type:        'table'
  searchable:  boolean                           // any column searchable
  defaultSort?: { column: string; direction: 'asc' | 'desc' }
  perPage?:    number

  // Reorderable rows (Table.reorderable):
  reorderable?:       true
  reorderableColumn?: string                     // model column the new order writes back to
  reorderUrl?:        string                     // POST target stamped server-side

  // Render-time state (set by loadTableRecords):
  rows?:        unknown[]
  total?:       number
  currentSort?: { column: string; direction: 'asc' | 'desc' }
  search?:      string
  currentPage?: number
}

Column.make('title')
  .label('Article title')   // defaults to capitalized name
  .sortable()
  .searchable()

Text.make('Active')
  .color('success')           // 'default' | 'muted' | 'primary' | 'destructive' | 'success' | 'warning' | 'info'
  .size('lg')                 // 'xs' | 'sm' | 'base' | 'lg' | 'xl'
  .weight('semibold')         // 'normal' | 'medium' | 'semibold' | 'bold'

Text.make('Pending')
  .badge()                    // pill rendering with the default 'gray' tint
  .badgeColor('warning')      // 'gray' | 'primary' | 'success' | 'warning' | 'destructive' | 'info' (implies badge)

import { registerIcons } from '@pilotiq/pilotiq/icons'
import { CheckCircle } from 'lucide-react'

registerIcons({ 'check-circle': CheckCircle })

Icon.make('check-circle').size(20).color('success').label('Done')

Markdown.make([
  '## Welcome',
  '',
  'Thanks for **trying** pilotiq.',
  '',
  '- Auto-converted via `marked`',
  '- GitHub-flavored by default',
].join('\n'))

Html.make('<p>Already-rendered <strong>HTML</strong> from a legacy column.</p>')

// Off entirely — admin-trusted source AND reader.
Markdown.make(post.body).allowRaw()
Html.make(legacyColumn).sanitize(false)

// Widen the allowlist for embedded media or inline color highlighters.
Html.make(cmsHtml).sanitize({
  allowedTags:        ['iframe', 'video', 'source'],
  allowedAttributes:  { iframe: ['src', 'width', 'height', 'allowfullscreen'] },
  allowedSchemes:     ['http', 'https'],
})

export class Disclosure extends Element {
  private constructor(private title: string) { super() }
  static make(title: string) { return new Disclosure(title) }

  schema(els: Element[]) { this._children = els; return this }

  getType() { return 'disclosure' }
  toMeta() { return { type: 'disclosure', title: this.title } }
}

import { registerResolver, type ElementResolver } from '@pilotiq/pilotiq'

const myResolver: ElementResolver = async (el, ctx, recurse) => {
  // 1. compute extra data from `el` and `ctx` (server-side only)
  const records = await db.fetch(/* … */)

  // 2. recurse children if you have a container
  const children = await recurse(el.getChildren() ?? [])

  // 3. return meta — must include `type`
  return { type: el.getType(), records, children }
}

registerResolver('my-custom-type', myResolver)

src/
├── schema/
│   ├── Element.ts           ← abstract base + ElementMeta
│   ├── resolveSchema.ts     ← resolver + registerResolver + RenderContext
│   ├── Text.ts, Heading.ts, Alert.ts, Divider.ts, Image.ts, Icon.ts, Markdown.ts, Html.ts   ← display leaves
│   └── Card.ts, Section.ts, Tabs.ts, Grid.ts       ← containers
├── fields/
│   ├── Field.ts             ← base Field, visibility, validators, FieldMeta
│   ├── TextField.ts, EmailField.ts, …              ← 8 concrete subclasses
│   └── resolveField.ts      ← per-field resolver (used by Resource until 1.6)
├── actions/
│   └── Action.ts            ← single class, placement-discriminated
└── validation/
    ├── Validator.ts         ← Validator type + makeValidator
    ├── rules.ts             ← required, email, minLength, ...
    └── runValidators.ts     ← validateSchema tree walker