FormBuilder

API / @publicodes/forms / FormBuilder

Defined in: formBuilder.ts:134

Type Parameters

Constructors

new FormBuilder()

new FormBuilder<RuleName>(__namedParameters): FormBuilder<RuleName>

Defined in: formBuilder.ts:139

Parameters

Returns

FormBuilder<RuleName>

Methods

currentPage()

currentPage(formState): CurrentPageElements<RuleName>

Defined in: formBuilder.ts:255

Retrieves the current form page with UI properties for rendering.

This method processes the current page of form fields and enhances them with UI-specific properties like visibility, focus state, and validation status. It’s typically used when rendering the form in your UI.

Parameters

Returns

CurrentPageElements<RuleName>

An array of form elements with UI properties and validation state

Example

// In a React component
const formElements = formBuilder.currentPage(formState)
return (
  <form>
    {formElements.map(element => (
      <FormField
        key={element.id}
        {...element}
        onChange={value => handleChange(element.id, value)}
      />
    ))}
  </form>
)

evaluate()

evaluate(formState, ruleName): EvaluatedNode<
  | "rule"
  | "replacementRule"
  | "une possibilité"
  | "arrondi"
  | "barème"
  | "condition"
  | "constant"
  | "contexte"
  | "durée"
  | "est non applicable"
  | "est non défini"
  | "grille"
  | "inversion"
  | "operation"
  | "reference"
  | "résoudre référence circulaire"
  | "simplifier unité"
  | "taux progressif"
  | "texte"
  | "unité"
  | "variable manquante"
  | "variations"
| "logarithme", EvaluatedValueTypes>

Defined in: formBuilder.ts:297

Wrapper around engine.evaluate that ensures proper reactivity in signal-based systems.

This method ensures the engine’s situation is up-to-date before evaluating a rule, making it suitable for use in reactive frameworks that track dependencies (like Svelte, Vue, Solid.js, or other signal-based systems).

Parameters

Returns

EvaluatedNode< | "rule" | "replacementRule" | "une possibilité" | "arrondi" | "barème" | "condition" | "constant" | "contexte" | "durée" | "est non applicable" | "est non défini" | "grille" | "inversion" | "operation" | "reference" | "résoudre référence circulaire" | "simplifier unité" | "taux progressif" | "texte" | "unité" | "variable manquante" | "variations" | "logarithme", EvaluatedValueTypes>

The evaluation result from the engine

Example

// In a reactive framework
const result = formBuilder.evaluate(formState, 'total . amount')
// The framework will track this dependency and re-run when formState changes

goToNextPage()

goToNextPage(formState): FormState<RuleName>

Defined in: formBuilder.ts:368

Advances the form to the next page in the sequence.

This method handles navigation to the next page, including:

• Moving to the next page if one exists in the current pages array
• Loading a new page from the nextPages queue if needed
• Returning the original state if there are no more pages

Parameters

Returns

FormState<RuleName>

A new form state positioned at the next page, or the original state if at the last page

Example

// Handle "Next" button click
function handleNext() {
  const nextState = formBuilder.goToNextPage(formState)
  setFormState(nextState)

  // Check if we actually moved to a new page
  if (nextState.currentPageIndex !== formState.currentPageIndex) {
    // Scroll to top or perform other navigation-related actions
    window.scrollTo(0, 0)
  }
}

goToPreviousPage()

goToPreviousPage(formState): FormState<RuleName>

Defined in: formBuilder.ts:410

Navigates to the previous page in the form.

This method decrements the current page index if possible, allowing users to go back to review or change their previous answers.

Parameters

Returns

FormState<RuleName>

A new form state positioned at the previous page, or the original state if already at the first page

Example

// Handle "Previous" button click
function handlePrevious() {
  const prevState = formBuilder.goToPreviousPage(formState)
  setFormState(prevState)

  // Optionally scroll to top when navigating
  window.scrollTo(0, 0)
}

handleInputChange()

handleInputChange(
   formState, 
   id, 
value): FormState<RuleName>

Defined in: formBuilder.ts:445

Updates the form state when a user changes an input value.

This method:

1. Records which field was last answered
2. Updates the engine’s situation with the new value
3. Recalculates which fields are needed next based on the new value
4. Updates the form state with the new situation and next pages

Parameters

Returns

FormState<RuleName>

A new form state with updated values and potentially new pages

Example

// In a React component
function handleChange(id, value) {
  const newState = formBuilder.handleInputChange(formState, id, value)
  setFormState(newState)

  // The form may have new pages based on this input
  console.log(`Next pages count: ${newState.nextPages.length}`)
}

pagination()

pagination(formState): object

Defined in: formBuilder.ts:331

Retrieves pagination information for building navigation controls.

This method calculates the current page position and total page count, along with boolean flags that can be used to enable/disable navigation buttons.

Parameters

Returns

object

An object containing pagination details:

• current - Current page number (1-based)
• pageCount - Total number of pages (known + upcoming)
• hasNextPage - Whether there is a next page available
• hasPreviousPage - Whether there is a previous page available

Example

// In a React component
const { current, pageCount, hasNextPage, hasPreviousPage } = formBuilder.pagination(formState)

return (
  <div className="pagination">
    <span>Page {current} of {pageCount}</span>
    <button disabled={!hasPreviousPage} onClick={handlePrevious}>Previous</button>
    <button disabled={!hasNextPage} onClick={handleNext}>Next</button>
  </div>
)

start()

start(formState, ...targets): FormState<RuleName>

Defined in: formBuilder.ts:210

Initializes a form with specified target rules and moves to the first page.

This method sets up a form by:

1. Registering the target rules that the form aims to compute
2. Determining which input fields are needed based on these targets
3. Organizing these fields into pages using the configured page builder
4. Moving to the first page of questions

Parameters

Returns

FormState<RuleName>

A new form state initialized with the first page of questions

Throws

Error if no targets are provided

Example

// Initialize a form with a single target
let state = FormBuilder.newState()
state = formBuilder.start(state, 'eligibility . result')

// Or with multiple targets
state = formBuilder.start(state, 'tax . amount', 'benefits . eligible')

newState()

static newState<RuleName>(situation): FormState<RuleName>

Defined in: formBuilder.ts:173

Creates a new, empty form state object.

This static method initializes a blank form state that can be used as the starting point for a new form. The state includes an optional initial situation (user answers).

Type Parameters

Parameters

Returns

FormState<RuleName>

A new form state object ready to be used with start()

Example

// Create an empty form state
const state = FormBuilder.newState()

// Create a form state with initial values
const stateWithValues = FormBuilder.newState({
  'user . age': 30,
  'user . income': 50000
})