1. Suite Overview

The **OpenForms** suite is a high-fidelity enterprise solution developed in **ES6 Vanilla JavaScript** and **Pure CSS**, with zero heavy external dependencies and strict compliance with modern design guidelines.

The system is modularized into two architectural fronts that communicate through a stable JSON contract (FormSchemaJSON):

• OpenFormBuilder (`src/builder.js`): The visual form builder for administrators. It manages the assembly of the responsive drag-and-drop grid, dynamic column resizing, and business rules in the properties panel.
• OpenFormRenderer (`src/renderer.js`): The interactive rendering engine for the end-user. It consumes the JSON schema, manages real-time answers, executes calculations, re-evaluates conditional logic, and ensures validation integrity before data submission.

2. Responsive Grid & Layout

The suite organizes the form layout into a 3-level structural tree:

• Pages: Provides native tab-based pagination. The player automatically renders an elegant step progress bar (Steps indicator) at the top to guide the user.
• Sections: Field groupings represented by visual cards (Section Cards) with customizable titles, allowing you to group data logically (e.g., Personal Details vs. Address).
• Rows & Columns: Each section has responsive grid rows. Each row supports up to 4 individual columns.

3. Available Widgets and Fields

The field palette offers a wide range of common draggable enterprise inputs for the canvas. Upon submission, answers are grouped and exported in the `FormAnswersJSON` payload:

4. Calculated Fields (Formula Engine) fx

Inputs of type number can be configured as calculated fields. The player renders these fields in read-only (readonly) mode, with a calculator icon and an inactive gray background.

• Key Placeholders: The formula must reference the technical keys of other numeric fields wrapped in braces (e.g., {unitPrice} * {quantity} * 1.15).
• Convergence Loop (Relaxation Loop): The calculation engine in the player runs in a recursive loop up to 5 times for every input change, dynamically resolving chained dependencies (formulas depending on other formulas, e.g., Subtotal -> Tax -> Grand Total) cleanly and instantly.
• Security Sandbox Whitelist: Expressions are strictly sanitized using a restrictive regex. Only numbers, operators (+, -, *, /, %), parentheses, ternary conditionals (? :), and explicitly whitelisted mathematical functions from the Math library (Math.round, Math.max, Math.min, Math.abs, Math.floor, Math.ceil) are authorized for execution, eliminating the risk of malicious script injection.

5. Custom Input Masking

Enables formatting and restricting input entry behaviors for text and number fields in real-time during typing:

• Supported Wildcards: - 9: Limits the character strictly to numeric digits (0-9). - a: Limits the character to alphabetical letters (a-z, A-Z). - *: Allows alphanumeric characters (letters or numbers).
• Practical Examples: 999.999.999-99 (CPF/Social Security), (99) 99999-9999 (Mobile Phone), aaaa-9999 (Asset Code).
• Cursor Tracking: An integrated algorithm tracks the cursor's position when removing or editing intermediate characters in the field, preventing jarring cursor jumps.
• Save Clean Value: A configurable option in the builder that automatically strips masking formatting, punctuations, and delimiters when persisting the answer in the final payload (e.g., a CPF entered as 123.456.789-00 is saved purely as 12345678900).

6. Conditional Business Rules (CNF Rules)

The builder has a visual configuration panel to define visibility and behavioral rules on fields and sections based on conjunctive normal form (AND of groups containing OR conditions):

• Mutable Properties: Logical rules are not limited to Visibility (visibility). They can also toggle Mandatory states (required - dynamically adding or removing the red asterisk and reactive validation rules) and Edit freezes (disabled - disabling inputs or freezing signature canvas interactions).
• Row Auto-Collapse (Gaps prevention): To prevent empty spaces or vertical gaps on the screen when multiple consecutive fields are hidden, the player detects if all elements within a responsive row (.renderer-row) are hidden, automatically applying display: none to the entire row to preserve a clean and compact layout.

7. Dynamic Localization & i18n

The suite stores structured language assets in a root schema dictionary (translations) indexed by their corresponding locales:

• Visual Selector in the Builder: Enables selecting the active property editing language (Labels, placeholders, choice options). The canvas updates instantly to simulate the translated form.
• Translational Safety Security: When editing in a non-default language (e.g., editing Portuguese on a base English form), critical structural inputs (such as database key, requirements, and conditional logic properties) are automatically disabled. This allows translators to localized labels safely without breaking business rules or system integrations.
• Dynamic Switching Method (setLocale): The player exposes a public setLocale(newLocale) method. When invoked, it translates all visual labels across the form instantly, preserving 100% of the active inputs and values entered by the user!

8. Advanced Cross-Field Validation

Allows configuring complex logical validations that relate multiple fields of the form to verify the overall integrity of the answers before authorizing submission:

• Temporal Date Comparisons: Logical date comparisons such as {endDate} >= {startDate} parse date strings formatted as YYYY-MM-DD into native numeric milliseconds (timestamps via Date.parse()), allowing secure mathematical validation checks without exposing security loopholes.
• Allocations & Quota Validations: Restricts the sum or ratio of multiple numeric fields (e.g., ({devShare} + {pmShare} + {qaShare}) <= 100).
• Feedback & Error Mapping: If a validation rule fails, all fields listed inside the rule's targetFields property receive the red is-invalid error wrap, and the custom error message is dynamically injected below each affected field.

9. Strict Accessibility (WCAG 2.1 Level AA)

The suite has been optimized under strict accessibility guidelines to ensure that all interactive elements can be comfortably navigated and operated by assistive technologies and screen readers:

• High-Visibility Focus Indicators: All buttons, dropdowns, inputs, page tabs, and custom interactive widgets (like the signature clear button) receive a clear outline: 2px solid var(--color-primary) !important keyboard focus ring.
• Accessible Keyboard Tabs: The page step navigation layout is constructed using semantic role="tablist" and role="tab" structures. Users can easily navigate between tabs using keyboard arrow keys (Left/Right) and activate steps using Space or Enter.
• Semantic HTML & ARIA Bindings: The player canvas is wrapped in a semantic <form> element mapped via aria-labelledby. Labels and inputs are strictly bound using matching id and for properties. Helpers and active validation errors are announced via aria-describedby, and error states are reatively signaled using aria-invalid="true".
• Live Regions & Busy States: Dynamic toasts are announced by screen readers via live region containers (aria-live="polite" or aria-live="assertive"), and asynchronous dropdown REST fetches signal active loads using aria-busy="true".

10. Undo & Redo with Global Shortcuts

The builder monitors the canvas state and manages structural history stacks performing deep JSON clones under the hood:

• Built-in Native Shortcuts: Full support for standard enterprise keyboard mappings: Ctrl + Z / Cmd + Z (Undo) and Ctrl + Y / Cmd + Shift + Z (Redo).
• Focus Collision Protection: The keyboard listener intelligently checks if the user's cursor is active inside a text input, select, or properties sidebar textarea, and **suspends structural shortcuts**, ensuring internal typing uses native browser text undo/redo without disrupting the form canvas layout.

11. Known Component Limitations

While **OpenForms** is a robust and flexible visual suite for creating and rendering JSON-driven dynamic forms, certain architectural constraints should be taken into account when integrating it in enterprise systems:

• No Support for Recurrent Circular Formulas: The formula engine resolves chained calculated fields, but direct or indirect circular references (e.g., Field A depends on B, and B depends on A) are not resolved and will be terminated after 5 relaxation iterations to prevent browser thread locks.
• File Upload Limited to the Browser: As the file uploader is standalone and written in Vanilla JS, files exceeding 5MB are not recommended for direct in-memory Base64 Data URL conversions, as they can cause browser memory constraints. For high-volume or massive file flows, events should be intercepted to perform uploads out-of-band.
• End-User Focused Accessibility (ATAG vs. WCAG): Full WCAG 2.1 Level AA compliance is rigorously implemented within the **OpenFormRenderer** (the interactive form player). The **OpenFormBuilder** (visual designer canvas) inherits active focus and keyboard indicators, but is not designed for screen-reader drag-and-drop visual grid block manipulation.
• REST API Dropdowns Without Infinite Scrolling: Options loaded via REST APIs are fetched in a single transaction during initial field rendering. The component does not natively support asynchronous server-side search querying or scroll-based pagination (infinite scrolling) inside dropdown selectors.

12. Using AI to Generate Custom Templates

You can leverage modern large language models (LLMs like Gemini, Claude, or GPT) to instantly generate pristine form templates. Simply copy and paste the prompt template below to guide the AI in generating perfectly structured forms that match our engine specification.

13. Web Applications Integration Guide (Vanilla JS / API)

Integrating the **OpenForms** suite into any website or web application is highly straightforward and relies completely on native web standards (Vanilla JS), requiring no external heavy frameworks:

Step 2: Declare the Target Wrapper and Instantiate the Player

Add a plain empty target container block in your HTML markup and initialize the OpenFormRenderer instance via JavaScript:

Step 3: Flexible Persistence

Submitted answers are exported as a flat JSON key-value object, allowing painless direct storage into relational databases or NoSQL backend clusters.