@fayz-ai/plugin-forms 0.2.0 → 0.8.1

package/src/components/FormBuilder.tsx

@@ -11,7 +11,7 @@ import {
 } from '@dnd-kit/core'
 import { arrayMove } from '@dnd-kit/sortable'
 import { snapCenterToCursor } from '@dnd-kit/modifiers'
-import { ArrowLeft, Eye } from 'lucide-react'
+import { ArrowLeft, Eye, Pencil, Printer } from 'lucide-react'
 import { Button, useSaveBar, toast } from '@fayz-ai/ui'
 import { Input } from '@fayz-ai/ui'
 import { Card, CardContent } from '@fayz-ai/ui'
@@ -24,6 +24,7 @@ import {
   SelectValue,
 } from '@fayz-ai/ui'
 import { useTranslation } from '@fayz-ai/core'
+import { useLimitGuard, invalidateLimit, useAgentSurface, type AgentSurfaceContribution } from '@fayz-ai/saas'
 import type { CustomFormsStore } from '../store'
 import type { CustomFormsDataProvider } from '../data/types'
 import type { CustomFormsConfig } from '../config'
@@ -33,6 +34,8 @@ import { BuilderCanvas } from './BuilderCanvas'
 import { FieldConfigDrawer } from './FieldConfigDialog'
 import { createPortal } from 'react-dom'
 import { FormRenderer } from './FormRenderer'
+import { buildPrintHtml } from '../lib/print'
+import { FORM_BUILDER_INSTRUCTIONS } from '../agent-tools'
 
 const TEMPLATE_CATEGORIES: TemplateCategory[] = ['anamnesis', 'evolution', 'report', 'contract', 'general']
 
@@ -46,6 +49,7 @@ interface FormBuilderProps {
 
 export function FormBuilder({ templateId, store, provider, config, onBack }: FormBuilderProps) {
   const t = useTranslation()
+  const guardTemplates = useLimitGuard('form_templates')
 
   const [name, setName] = useState('')
   const [description, setDescription] = useState('')
@@ -54,6 +58,7 @@ export function FormBuilder({ templateId, store, provider, config, onBack }: For
   const [selectedFieldId, setSelectedFieldId] = useState<string | null>(null)
   const [saving, setSaving] = useState(false)
   const [showPreview, setShowPreview] = useState(false)
+  const [previewMode, setPreviewMode] = useState<'editor' | 'print'>('editor')
   const [previewData, setPreviewData] = useState<Record<string, unknown>>({})
   const [draggingFieldType, setDraggingFieldType] = useState<import('../types').FormFieldType | null>(null)
   const [templateName, setTemplateName] = useState<string | null>(null)
@@ -139,6 +144,48 @@ export function FormBuilder({ templateId, store, provider, config, onBack }: For
     setFields((prev) => prev.map((f) => (f.id === updated.id ? updated : f)))
   }, [])
 
+  // --- Assistant surface: publish WHAT THE USER IS EDITING as context --------
+  // The build action is the server-plane createOrUpdateForm tool (a pool RPC),
+  // which works from any page. This surface only tells the model which template
+  // is open and its current fields+ids, so "add an allergies field to THIS
+  // form" resolves to the right templateId. No client-side mutation here.
+  const surfaceStateRef = React.useRef({ templateId, name, description, category, fields })
+  surfaceStateRef.current = { templateId, name, description, category, fields }
+
+  const agentSurface = React.useMemo<AgentSurfaceContribution>(
+    () => ({
+      id: 'custom_forms.builder',
+      pluginId: 'custom_forms',
+      instructions: FORM_BUILDER_INSTRUCTIONS,
+      describe: () => {
+        const o = surfaceStateRef.current
+        return {
+          title: `Construtor de formulário — ${o.name?.trim() || 'novo modelo'}`,
+          state: {
+            // Pass this as `templateId` to createOrUpdateForm when editing THIS
+            // form. Null = an unsaved new form (create, then it gets an id).
+            templateId: o.templateId ?? null,
+            unsaved: !o.templateId,
+            name: o.name ?? '',
+            category: o.category ?? 'general',
+            description: o.description ?? '',
+            fieldCount: o.fields.length,
+            fields: o.fields.map((f) => ({
+              id: f.id,
+              type: f.type,
+              label: f.label,
+              required: !!f.required,
+              ...(f.options?.length ? { options: f.options.map((x) => x.label) } : {}),
+            })),
+          },
+        }
+      },
+    }),
+    [],
+  )
+  useAgentSurface(agentSurface)
+  // ---------------------------------------------------------------------------
+
   const handleFieldConfigSave = useCallback((updated: FormFieldDef) => {
     handleFieldUpdate(updated)
     setSelectedFieldId(null)
@@ -146,6 +193,9 @@ export function FormBuilder({ templateId, store, provider, config, onBack }: For
 
   const handleSave = useCallback(async () => {
     if (!name.trim()) { toast.error(t('common.formIncomplete')); return }
+    // Plan quantity guard (client-side, before the provider call) — only on
+    // create. Opens the global UpgradeModal and aborts when the cap is reached.
+    if (!templateId && (await guardTemplates()) === 'blocked') return
     setSaving(true)
     try {
       const schema: FormSchema = { fields, layout: { columns: 12 } }
@@ -154,12 +204,13 @@ export function FormBuilder({ templateId, store, provider, config, onBack }: For
         await store.getState().updateTemplate(templateId, { name, description, category, schema })
       } else {
         await store.getState().createTemplate({ name, description, category, schema })
+        invalidateLimit('form_templates')
       }
       onBack()
     } finally {
       setSaving(false)
     }
-  }, [templateId, name, description, category, fields, store, onBack])
+  }, [templateId, name, description, category, fields, store, onBack, guardTemplates])
 
   // Dirty detection — snapshot editable fields once async load settles
   const currentFields = { name, description, category, fields }
@@ -260,7 +311,7 @@ export function FormBuilder({ templateId, store, provider, config, onBack }: For
             size="sm"
             className="h-9"
             disabled={fields.length === 0}
-            onClick={() => { setPreviewData({}); setShowPreview(true) }}
+            onClick={() => { setPreviewData({}); setPreviewMode('editor'); setShowPreview(true) }}
           >
             <Eye className="h-3.5 w-3.5 mr-1.5" />
             Preview
@@ -316,26 +367,57 @@ export function FormBuilder({ templateId, store, provider, config, onBack }: For
             style={{ minHeight: '80vh' }}
             onClick={(e) => e.stopPropagation()}
           >
-            {/* Close button — kept on white paper background; literal grays are intentional print look */}
-            <button
-              onClick={() => setShowPreview(false)}
-              className="absolute top-3 right-3 z-10 flex h-8 w-8 items-center justify-center rounded-full text-neutral-400 hover:bg-neutral-100 hover:text-neutral-700 transition-colors"
-            >
-              <span className="text-lg">✕</span>
-            </button>
-
-            {/* Paper content — printed A4 simulation; literal black-on-white is the point */}
-            <div className="px-10 py-8 sm:px-14 sm:py-10 text-neutral-900">
-              <h1 className="text-2xl font-bold mb-1">{name || t('customForms.newTemplate')}</h1>
-              {description && <p className="text-sm text-neutral-500 mb-8">{description}</p>}
-              {!description && <div className="mb-8" />}
-
-              <FormRenderer
-                schema={{ fields, layout: { columns: 12 } }}
-                data={previewData}
-                onChange={setPreviewData}
-              />
+            {/* Toggle Editor ⟷ Impressão (centered) + close, on a sticky top bar. */}
+            <div className="sticky top-0 z-10 flex items-center justify-center border-b bg-white/95 backdrop-blur px-4 py-2.5 rounded-t-modal">
+              <div className="inline-flex rounded-lg border p-0.5 text-xs">
+                <button
+                  onClick={() => setPreviewMode('editor')}
+                  className={`inline-flex items-center gap-1.5 px-3 py-1 rounded-md font-medium transition-colors ${previewMode === 'editor' ? 'bg-neutral-900 text-white' : 'text-neutral-500 hover:text-neutral-800'}`}
+                >
+                  <Pencil className="h-3.5 w-3.5" />
+                  {t('customForms.preview.editor')}
+                </button>
+                <button
+                  onClick={() => setPreviewMode('print')}
+                  className={`inline-flex items-center gap-1.5 px-3 py-1 rounded-md font-medium transition-colors ${previewMode === 'print' ? 'bg-neutral-900 text-white' : 'text-neutral-500 hover:text-neutral-800'}`}
+                >
+                  <Printer className="h-3.5 w-3.5" />
+                  {t('customForms.preview.print')}
+                </button>
+              </div>
+              <button
+                onClick={() => setShowPreview(false)}
+                className="absolute right-3 top-1/2 -translate-y-1/2 flex h-8 w-8 items-center justify-center rounded-full text-neutral-400 hover:bg-neutral-100 hover:text-neutral-700 transition-colors"
+              >
+                <span className="text-lg">✕</span>
+              </button>
             </div>
+
+            {previewMode === 'editor' ? (
+              /* Editor — fillable form (same renderer used on the person's ficha) */
+              <div className="px-10 py-8 sm:px-14 sm:py-10 text-neutral-900">
+                <h1 className="text-2xl font-bold mb-1">{name || t('customForms.newTemplate')}</h1>
+                {description && <p className="text-sm text-neutral-500 mb-8">{description}</p>}
+                {!description && <div className="mb-8" />}
+
+                <FormRenderer
+                  schema={{ fields, layout: { columns: 12 } }}
+                  data={previewData}
+                  onChange={setPreviewData}
+                />
+              </div>
+            ) : (
+              /* Impressão — exact print/PDF output rendered in an isolated iframe */
+              <iframe
+                title="print-preview"
+                className="w-full rounded-b-modal"
+                style={{ height: '75vh', border: 'none' }}
+                srcDoc={buildPrintHtml(
+                  { id: 'preview', name: name || t('customForms.newTemplate'), schema: { fields, layout: { columns: 12 } } } as any,
+                  { title: name || t('customForms.newTemplate'), createdAt: new Date().toISOString(), status: 'draft', data: previewData } as any,
+                )}
+              />
+            )}
           </div>
         </div>,
         document.body,

package/src/components/FormViewer.tsx

@@ -1,11 +1,12 @@
 import React, { useEffect, useState } from 'react'
-import { ArrowLeft, Pencil, Badge as BadgeIcon } from 'lucide-react'
+import { ArrowLeft, Pencil, Printer } from 'lucide-react'
 import { Button } from '@fayz-ai/ui'
 import { Badge } from '@fayz-ai/ui'
 import { useTranslation } from '@fayz-ai/core'
 import type { CustomFormsDataProvider } from '../data/types'
 import type { FormDocument, FormTemplate } from '../types'
 import { FormRenderer } from './FormRenderer'
+import { printDocument } from '../lib/print'
 
 interface FormViewerProps {
   document: FormDocument
@@ -62,6 +63,15 @@ export function FormViewer({ document: doc, provider, onBack, onEdit }: FormView
         <Badge variant="secondary" className={`text-[10px] ${STATUS_COLORS[doc.status] ?? ''}`}>
           {t(`customForms.status.${doc.status}`)}
         </Badge>
+        <Button
+          variant="outline"
+          size="sm"
+          className="h-8"
+          onClick={() => printDocument(template, doc)}
+        >
+          <Printer className="h-3 w-3 mr-1" />
+          {t('customForms.printPdf')}
+        </Button>
         {onEdit && doc.status === 'draft' && (
           <Button variant="outline" size="sm" className="h-8" onClick={() => onEdit(doc)}>
             <Pencil className="h-3 w-3 mr-1" />

package/src/components/PersonDocumentsWidget.tsx

@@ -2,6 +2,7 @@ import React, { useState, useCallback, useRef } from 'react'
 import { ArrowLeft, Image as ImageIcon, Paperclip } from 'lucide-react'
 import { Badge } from '@fayz-ai/ui'
 import { useTranslation } from '@fayz-ai/core'
+import { useLimitGuard, invalidateLimit } from '@fayz-ai/saas'
 import type { CustomFormsConfig } from '../config'
 import type { CustomFormsDataProvider } from '../data/types'
 import type { CustomFormsStore } from '../store'
@@ -27,6 +28,7 @@ type WidgetView =
 
 export function PersonDocumentsWidget({ item, config, provider, store }: PersonDocumentsWidgetProps) {
   const t = useTranslation()
+  const guardDocuments = useLimitGuard('documents_month')
   const [view, setView] = useState<WidgetView>({ type: 'list' })
   const fileInputRef = useRef<HTMLInputElement>(null)
   const [pendingFileAccept, setPendingFileAccept] = useState<string>('*/*')
@@ -58,6 +60,10 @@ export function PersonDocumentsWidget({ item, config, provider, store }: PersonD
   }, [provider])
 
   const handleFiles = useCallback(async (files: File[]) => {
+    // Plan monthly-quota guard (client-side, before the provider call) — count
+    // the whole batch. Opens the global UpgradeModal and aborts when the cap
+    // would be exceeded.
+    if ((await guardDocuments(files.length)) === 'blocked') return
     for (const file of files) {
       const isImage = file.type.startsWith('image/')
       await store.getState().createDocument({
@@ -70,7 +76,8 @@ export function PersonDocumentsWidget({ item, config, provider, store }: PersonD
         status: 'completed',
       })
     }
-  }, [store, item.id])
+    invalidateLimit('documents_month')
+  }, [store, item.id, guardDocuments])
 
   const handleFileInputChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
     const files = Array.from(e.target.files ?? [])
@@ -101,6 +108,7 @@ export function PersonDocumentsWidget({ item, config, provider, store }: PersonD
         template={view.template}
         personId={item.id}
         personName={item.name}
+        person={item}
         provider={provider}
         store={store}
         onSaved={handleSaved}
@@ -139,6 +147,7 @@ export function PersonDocumentsWidget({ item, config, provider, store }: PersonD
         existingDocument={view.document}
         personId={item.id}
         personName={item.name}
+        person={item}
         provider={provider}
         store={store}
         onSaved={handleSaved}

package/src/data/supabase.ts

@@ -13,6 +13,7 @@ import type {
   UpdateDocumentInput,
 } from '../types'
 import { getSupabaseClientOptional, getActiveTenantId } from '@fayz-ai/core'
+import { T } from './tables'
 
 function getTenantId(): string {
   // Local override wins; else use the app's active tenant so writes pass RLS.
@@ -102,11 +103,13 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
     async getTemplates(query: TemplateQuery): Promise<PaginatedResult<FormTemplate>> {
       const db = getClient()
       let qb = db
-        .from('frm_templates')
+        .from(T.templates)
         .select('*', { count: 'exact' })
         .eq('tenant_id', getTenantId())
         .eq('is_current', true)
         .eq('is_deleted', false)
+        // Archived templates (isActive=false) leave the list and the picker.
+        .eq('is_active', true)
 
       if (query.category) qb = qb.eq('category', query.category)
       if (query.search) qb = qb.ilike('name', `%${query.search}%`)
@@ -125,7 +128,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
     async getTemplateById(id: string): Promise<FormTemplate | null> {
       const db = getClient()
       const { data, error } = await db
-        .from('frm_templates')
+        .from(T.templates)
         .select('*')
         .eq('id', id)
         .eq('is_deleted', false)
@@ -138,7 +141,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
       const db = getClient()
       const tenantId = getTenantId()
       const { data, error } = await db
-        .from('frm_templates')
+        .from(T.templates)
         .insert({
           tenant_id: tenantId,
           name: input.name,
@@ -160,7 +163,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
       const tenantId = getTenantId()
 
       const { count } = await db
-        .from('frm_documents')
+        .from(T.documents)
         .select('document_id', { count: 'exact', head: true })
         .eq('template_id', id)
 
@@ -171,7 +174,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
         if (!existing) throw new Error('Template not found')
 
         const { data: newRow, error: insertError } = await db
-          .from('frm_templates')
+          .from(T.templates)
           .insert({
             tenant_id: tenantId,
             name: input.name ?? existing.name,
@@ -191,7 +194,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
         if (insertError) throw new Error(insertError.message)
 
         await db
-          .from('frm_templates')
+          .from(T.templates)
           .update({ is_current: false, updated_at: new Date().toISOString() })
           .eq('id', id)
 
@@ -209,7 +212,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
       if (input.isActive !== undefined) updates.is_active = input.isActive
 
       const { data, error } = await db
-        .from('frm_templates')
+        .from(T.templates)
         .update(updates)
         .eq('id', id)
         .select()
@@ -221,13 +224,13 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
     async deleteTemplate(id: string): Promise<void> {
       const db = getClient()
       const { error } = await db
-        .from('frm_templates')
+        .from(T.templates)
         .update({ is_deleted: true, updated_at: new Date().toISOString() })
         .eq('id', id)
       if (error) throw new Error(error.message)
     },
 
-    // ── Documents (saas_core.documents + frm_documents extension) ──
+    // ── Documents (public.documents + plg_forms_documents extension) ──
 
     async getDocuments(query: DocumentQuery): Promise<PaginatedResult<FormDocument>> {
       const db = getClient()
@@ -272,9 +275,9 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
       const tenantId = getTenantId()
       const isForm = !!input.templateId
 
-      // Step 1: Insert into saas_core.documents
+      // Step 1: Insert into public.documents
       const { data: coreDoc, error: coreError } = await getClient()
-        .from('frm_core_documents')
+        .from('documents')
         .insert({
           tenant_id: tenantId,
           kind: input.kind ?? (isForm ? 'form' : 'attachment'),
@@ -295,7 +298,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
       if (isForm && input.templateId) {
         const db = getClient()
         const { error: extError } = await db
-          .from('frm_documents')
+          .from(T.documents)
           .insert({
             document_id: coreDoc.id,
             tenant_id: tenantId,
@@ -304,7 +307,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
           })
         if (extError) {
           // Rollback core insert
-          await getClient().from('frm_core_documents').delete().eq('id', coreDoc.id)
+          await getClient().from('documents').delete().eq('id', coreDoc.id)
           throw new Error(extError.message)
         }
       }
@@ -324,7 +327,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
       if (input.notes !== undefined) coreUpdates.notes = input.notes
 
       const { error: coreError } = await getClient()
-        .from('frm_core_documents')
+        .from('documents')
         .update(coreUpdates)
         .eq('id', id)
       if (coreError) throw new Error(coreError.message)
@@ -333,7 +336,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
       if (input.data !== undefined) {
         const db = getClient()
         await db
-          .from('frm_documents')
+          .from(T.documents)
           .update({ data: input.data, updated_at: now })
           .eq('document_id', id)
       }
@@ -344,7 +347,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
 
     async deleteDocument(id: string): Promise<void> {
       const { error } = await getClient()
-        .from('frm_core_documents')
+        .from('documents')
         .update({ is_active: false, updated_at: new Date().toISOString() })
         .eq('id', id)
       if (error) throw new Error(error.message)
@@ -355,7 +358,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
     async getDocumentFiles(documentId: string): Promise<DocumentFile[]> {
       const db = getClient()
       const { data, error } = await db
-        .from('frm_document_files')
+        .from(T.documentFiles)
         .select('*')
         .eq('document_id', documentId)
         .order('sort_order')
@@ -377,7 +380,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
       const { data: urlData } = db.storage.from('documents').getPublicUrl(storagePath)
 
       const { data, error } = await db
-        .from('frm_document_files')
+        .from(T.documentFiles)
         .insert({
           tenant_id: tenantId,
           document_id: documentId,
@@ -396,7 +399,7 @@ export function createSupabaseFormsProvider(): CustomFormsDataProvider {
     async deleteFile(fileId: string): Promise<void> {
       const db = getClient()
       const { error } = await db
-        .from('frm_document_files')
+        .from(T.documentFiles)
         .delete()
         .eq('id', fileId)
       if (error) throw new Error(error.message)

package/src/data/tables.ts

@@ -0,0 +1,7 @@
+// Central physical-table-name registry for plugin-forms. `documents` stays core.
+export const T = {
+  documents: 'plg_forms_documents',
+  templates: 'plg_forms_templates',
+  documentFiles: 'plg_forms_document_files',
+  categories: 'plg_forms_categories',
+} as const

package/src/index.ts

@@ -1,6 +1,7 @@
 import React from 'react'
 import type { PluginManifest } from '@fayz-ai/core'
 import type { CustomFormsDataProvider } from './data/types'
+import { T } from './data/tables'
 import { createMockFormsProvider } from './data/mock'
 import { createSupabaseFormsProvider } from './data/supabase'
 import { createSafeDataProvider, registerTranslations } from '@fayz-ai/core'
@@ -12,6 +13,7 @@ import type { CustomFormsPluginOptions } from './config'
 import { CustomFormsSettingsTab } from './views/CustomFormsSettingsTab'
 import { PersonDocumentsWidget as PersonDocumentsWidgetImpl } from './components/PersonDocumentsWidget'
 import { registerDocumentTypeProvider } from './document-types'
+import { createOrUpdateFormTool } from './agent-tools'
 import { FileText as FileTextIcon, Image as ImageIcon, Paperclip } from 'lucide-react'
 
 function registerBuiltInProviders(formsProvider: CustomFormsDataProvider) {
@@ -82,7 +84,7 @@ export function createCustomFormsPlugin(options?: CustomFormsPluginOptions): Plu
           { key: 'isActive', label: 'Active', type: 'boolean' as const, showInTable: true, defaultValue: true, inlineToggle: true },
         ],
         data: {
-          table: 'frm_categories',
+          table: T.categories,
           tenantScoped: true,
         },
       },
@@ -104,6 +106,9 @@ export function createCustomFormsPlugin(options?: CustomFormsPluginOptions): Plu
     React.createElement(PluginSettingsPanel, {
       title: config.labels.settingsLabel,
       subtitle: config.labels.settingsSubtitle,
+      // The settings shell already renders the section label as the page H1;
+      // hide the panel's own duplicate title (keeps the subtitle).
+      hideTitle: true,
       customTabs: [
         {
           id: 'forms',
@@ -134,6 +139,10 @@ export function createCustomFormsPlugin(options?: CustomFormsPluginOptions): Plu
     declaredFeatures: [
       { id: 'custom_forms', label: config.labels.pageTitle, group: config.labels.pageTitle },
     ],
+    declaredLimits: [
+      { key: 'form_templates', label: 'Form templates', table: 'plg_forms_templates' },
+      { key: 'documents_month', label: 'Documents / month', table: 'documents', period: 'month' },
+    ],
 
     navigation: [],
 
@@ -205,6 +214,19 @@ export function createCustomFormsPlugin(options?: CustomFormsPluginOptions): Plu
         ],
         permission: { feature: 'custom_forms', action: 'read' as const },
       },
+      // Server-plane write: builds/edits a form template via the pool RPC, so
+      // the assistant can montar formulários from any page or channel.
+      createOrUpdateFormTool,
+    ],
+
+    declaredRpcs: [
+      {
+        name: 'agent_forms_upsert_template',
+        kind: 'write' as const,
+        description:
+          'Guarded form-template upsert: agent_guard (role→plan→form_templates cap), grid layout computed server-side, create or edit by id, audited.',
+        audits: true,
+      },
     ],
 
     locales: customFormsLocales,

package/src/lib/person-fields.ts

@@ -0,0 +1,67 @@
+// ============================================================
+// PERSON FIELD MAPPING — prefill a document from a person record
+// ============================================================
+//
+// A template field can declare `map: '<personKey>'` (see FormFieldDef.map).
+// When a document is created from a person's profile, fields with a mapping are
+// pre-filled from that person's record. The person record reaching the widget
+// is the host app's CRUD detail `item`, keyed by the entity's field keys
+// (camelCase, e.g. `documentNumber`). We resolve tolerantly so the same mapping
+// works whether the host exposes camelCase or snake_case keys.
+
+import type { FormSchema } from '../types'
+
+/** Curated, vertical-agnostic person keys offered in the field builder. */
+export const PERSON_FIELD_OPTIONS: Array<{ value: string; labelKey: string }> = [
+  { value: 'name', labelKey: 'customForms.personField.name' },
+  { value: 'documentNumber', labelKey: 'customForms.personField.documentNumber' },
+  { value: 'email', labelKey: 'customForms.personField.email' },
+  { value: 'phone', labelKey: 'customForms.personField.phone' },
+  { value: 'dateOfBirth', labelKey: 'customForms.personField.dateOfBirth' },
+  { value: 'guardianName', labelKey: 'customForms.personField.guardianName' },
+  { value: 'address', labelKey: 'customForms.personField.address' },
+  { value: 'city', labelKey: 'customForms.personField.city' },
+  { value: 'state', labelKey: 'customForms.personField.state' },
+]
+
+const toSnake = (k: string) => k.replace(/[A-Z]/g, (m) => '_' + m.toLowerCase())
+const toCamel = (k: string) => k.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase())
+
+/** Read a person field value, tolerating camelCase/snake_case key variants. */
+export function resolvePersonValue(
+  person: Record<string, unknown> | undefined | null,
+  mapKey: string | undefined,
+): unknown {
+  if (!person || !mapKey) return undefined
+  for (const key of [mapKey, toSnake(mapKey), toCamel(mapKey)]) {
+    const v = person[key]
+    if (v != null && v !== '') return v
+  }
+  return undefined
+}
+
+/**
+ * Build the initial document data for a template. For each field, applies (in
+ * priority order) an existing value, then the mapped person value, then the
+ * field's static `defaultValue`. Never overwrites a value already present in
+ * `existing`.
+ */
+export function prefillFromPerson(
+  schema: FormSchema | undefined,
+  person: Record<string, unknown> | undefined | null,
+  existing: Record<string, unknown> = {},
+): Record<string, unknown> {
+  const data: Record<string, unknown> = { ...existing }
+  if (!schema) return data
+  for (const field of schema.fields) {
+    const current = data[field.id]
+    if (current != null && current !== '') continue
+    const mapped = field.map ? resolvePersonValue(person, field.map) : undefined
+    if (mapped != null) {
+      data[field.id] = mapped
+    } else if (field.defaultValue != null) {
+      data[field.id] = field.defaultValue
+    }
+  }
+  return data
+}