API Reference
Complete API documentation for @seanblock/form-builder components, hooks, and types.
FormBuilderV3
Main component for rendering forms.
Props
| Prop | Type | Required | Description |
|---|---|---|---|
| config | FormConfig | ✅ Yes | Form configuration object |
| context | DynamicContext | ✅ Yes | Initial context/data |
| additionalBlocks | Record<string, BlockComponent> | No | Custom block components |
| secretContext | SecretContext | No | 🔒 Encrypted secrets (tokens, passwords) |
| encryptionKey | string | No | 🔒 Key for decrypting secretContext |
| customFunctions | Record<string, CustomFunction> | No | Custom function implementations |
| showDebug | boolean | No | Show debug panel |
| enableClientEncryption | boolean | No | 🔒 Enable client-side encryption (default: true) |
| auditLogging | AuditLogger | No | 🔒 Custom audit logger for security events |
Usage
import FormBuilderV3, { encryptValue } from '@seanblock/form-builder';
// Basic usage
<FormBuilderV3
config={formConfig}
context={initialContext}
additionalBlocks={customBlocks}
showDebug={true}
/>
// With encrypted secrets (recommended for production)
const encryptionKey = process.env.FORM_ENCRYPTION_KEY!;
const secretContext = {
apiToken: encryptValue('your-token', encryptionKey),
apiKey: encryptValue('your-key', encryptionKey),
};
<FormBuilderV3
config={formConfig}
context={initialContext}
secretContext={secretContext}
encryptionKey={encryptionKey}
additionalBlocks={customBlocks}
customFunctions={customFunctions}
/>useFormBuilder Hook
Access form state and methods in custom blocks.
Return Value
| Property | Type | Description |
|---|---|---|
| context | DynamicContext | Current form data |
| updateContextValue | (path, value) => void | Update form data at path |
| executeAction | (action) => Promise<void> | Execute single action |
| executeActions | (actions[]) => Promise<void> | Execute multiple actions |
| currentPage | string | Current page ID |
| setCurrentPage | (pageId) => void | Navigate to page |
| invalidList | string[] | List of invalid field IDs |
| errors | Error[] | General errors |
| isLoading | boolean | API loading state |
| config | FormConfig | Form configuration |
| importedBlocks | Record<string, Component> | Registered blocks |
Usage
import { useFormBuilder } from '@seanblock/form-builder';
function CustomBlock() {
const {
context,
updateContextValue,
executeActions,
currentPage,
isLoading
} = useFormBuilder();
// Use the hook values...
}Types
FormConfig
interface FormConfig {
id: string;
type: "form";
metadata?: {
formName?: string;
[key: string]: any;
};
initialPage: string;
context: DynamicContext;
services?: Record<string, ServiceDefinition>;
blocks?: Block[];
pages: Record<string, Block>;
}Block
interface Block {
id: string;
blockType: string;
className?: string;
style?: React.CSSProperties;
metadata?: Record<string, any>;
displayConditions?: Condition[];
blocks?: Block[];
actions?: Action[];
validations?: ValidateRule[];
}Action Types
type Action =
| { type: "goToPage"; target: string }
| { type: "callApi"; service: string; then?: Action[]; else?: Action[] }
| { type: "assignContext"; assign: Record<string, any> }
| { type: "assignSecret"; assign: Record<string, any>; encrypt?: boolean } // 🔒 New
| { type: "validate"; targets: string[] }
| { type: "validateCurrentPage"; then?: Action[]; else?: Action[] }
| { type: "conditional"; conditions: Condition[]; then: Action[]; else?: Action[] }
| { type: "toast"; message: string; variant?: string };🔒 New in v0.1.1: The assignSecret action allows you to update encrypted secrets. Set encrypt: true to automatically encrypt values before storing.
Validation Rules
interface ValidateRule {
rule: "charMinLength" | "charMaxLength" | "exact" | "pattern" | "isValid";
value?: any;
message: string;
}Available Standard Blocks
| Block Type | Category | Description |
|---|---|---|
| PageBlock | Layout | Page container |
| PageHeaderBlock | Layout | Page header |
| PageContentBlock | Layout | Page content |
| PageFooterBlock | Layout | Page footer |
| CardBlock | Layout | Content card |
| RowBlock | Layout | Horizontal layout |
| SidebarBlock | Layout | Sidebar container |
| HeaderBlock | Content | Heading text |
| ParagraphBlock | Content | Paragraph text |
| LinkBlock | Content | Hyperlink |
| ButtonBlock | Action | Button with actions |