Elaborate comments in FormData.js for improved clarity and maintainability

[Copilot]

Overview

This PR addresses Issue CurriculumAssociates#164 by elaborating the comments in src/RoleObjects/FormData.js to provide detailed explanations for each function, logic, and important sections of the code.

Changes Made

Class-Level Documentation

Added comprehensive JSDoc documentation explaining that FormData is a data structure for form roles that extends SectionData to provide form-specific properties mapping to HTML form attributes, enabling proper form submission and validation behavior in the accessibility layer.

Enhanced Property Documentation

Each getter/setter pair now includes detailed explanations:

• charSet: Documents character encoding acceptance (e.g., UTF-8, ISO-8859-1), explains the mapping to the acceptCharset React prop, and clarifies the camelCase conversion to the HTML accept-charset attribute.

• action: Explains the form submission URL endpoint with examples of absolute and relative URLs, and notes the default behavior when not set.

• autoComplete: Documents the boolean-to-string conversion logic that transforms true/false to 'on'/'off' as required by HTML, and explains the default enabled behavior.

• enctype: Details the MIME types for encoding form data, lists common values (application/x-www-form-urlencoded, multipart/form-data, text/plain) with their use cases, and clarifies that this only applies when using POST method.

• method: Explains HTTP methods (get, post, dialog) with detailed use cases, security implications, and limitations of each approach.

• name: Documents form identification purposes including JavaScript referencing, server-side processing, and differentiating multiple forms, while clarifying the distinction between name and id attributes.

• validate: Provides detailed explanation of the novalidate inversion logic - why the boolean is inverted (HTML uses "novalidate" where presence means no validation, but the API exposes "validate" where true means validation enabled for a more intuitive interface).

• target: Documents all common browsing context values (_self, _blank, _parent, _top) and custom frame names, explaining where form responses will be displayed.

Inline Comments

Added explanatory inline comments for complex logic:

• React prop mapping conversions (acceptCharset, encType)
• Boolean inversion logic with clear rationale
• Default behavior explanations

Impact

• File size: Grew from 150 to 270 lines (+152 insertions, -32 deletions)
• No functional changes: All 529 tests pass
• Code quality maintained: No linting issues, build succeeds, Prettier formatting validated

These elaborated comments significantly improve code clarity and maintainability by helping developers understand:

1. What each property controls
2. How values are transformed internally
3. Valid values and their effects
4. Relationships to HTML form attributes
5. Default behaviors when properties are not set

Original prompt

Make changes to the file src/RoleObjects/FormData.js by elaborating the comments as described in Issue #164. The updated comments should provide detailed explanations for each function, logic, and important sections of the code to improve clarity and maintainability.

This pull request was created as a result of the following prompt from Copilot chat.

Make changes to the file src/RoleObjects/FormData.js by elaborating the comments as described in Issue #164. The updated comments should provide detailed explanations for each function, logic, and important sections of the code to improve clarity and maintainability.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[nmahesh-cainc]

Changes as per the issue are made.