API Reference

Complete reference for Form System APIs.

DashForm

Main form provider component

The DashForm component wraps your form and provides the reactive engine, reactions, and runtime store.

import { DashForm } from '@dashforge/ui';

<DashForm
  reactions={reactions}
  defaultValues={{ country: 'United States' }}
  onSubmit={(data) => console.log(data)}
>
  {/* form fields */}
</DashForm>

Prop	Type	Default	Description
reactions	ReactionDefinition[]	[]	Array of reaction definitions for dynamic behavior
onSubmit	(data: FormValues) => void \| Promise<void>	required	Form submission handler
defaultValues	Partial<FormValues>	-	Initial form values
children	React.ReactNode	required	Form fields and content

ReactionDefinition

Reaction configuration object

Reactions are defined as objects with these properties:

Prop	Type	Default	Description
id	string	required	Unique identifier
watch	string[]	required	Field names to watch
when	(ctx: WhenContext) => boolean	-	Optional condition
run	(ctx: RunContext) => void \| Promise<void>	required	Effect to execute

RunContext

Context object passed to reaction run function

The run context provides methods for reading/writing form state:

Prop	Type	Default	Description
getValue<T>(name)	(name: string) => T	-	Read field value
setValue(name, value)	(name: string, value: unknown) => void	-	Update field value
getRuntime<TData>(name)	(name: string) => FieldRuntimeState<TData>	-	Read runtime state
setRuntime<TData>(name, patch)	(name: string, patch: Partial<FieldRuntimeState<TData>>) => void	-	Update runtime state
beginAsync(key)	(key: string) => number	-	Start async operation
isLatest(key, id)	(key: string, requestId: number) => boolean	-	Check if response is valid

FieldRuntimeState

Runtime metadata structure

Runtime state stores async metadata separate from form values:

interface FieldRuntimeState<TData = unknown> {
  status: 'idle' | 'loading' | 'ready' | 'error';
  data: TData | null;
  error: string | null;
}

Prop	Type	Default	Description
status	'idle' \| 'loading' \| 'ready' \| 'error'	'idle'	Current operation status
data	TData \| null	null	Runtime data (e.g., options)
error	string \| null	null	Error message if status is error

visibleWhen

Conditional visibility prop

All form components accept a visibleWhen prop for conditional rendering:

visibleWhen?: (engine: Engine) => boolean

// Example
<TextField
  name="companyName"
  label="Company Name"
  visibleWhen={(engine) => 
    engine.getNode('accountType')?.value === 'business'
  }
/>

optionsFromFieldData

Dynamic options prop

Select and Autocomplete components can load options from runtime state:

<Select
  name="state"
  label="State"
  optionsFromFieldData
/>

// Runtime state structure expected:
{
  status: 'ready',
  data: {
    options: ['California', 'Texas', 'New York']
  }
}