add documentation and tests for form builder functionality DEV-2268

[jamesrkiger]

🗒️ Checklist

1. run linter locally
2. update developer docs (API, README, inline, etc.), if any
3. for user-facing doc changes create a Zulip thread at #Support Docs Updates, if any
4. draft PR with a title <type>(<scope>)<!>: <title> DEV-1234
5. assign yourself, tag PR: at least Front end and/or Back end or workflow
6. fill in the template below and delete template comments
7. review thyself: read the diff and repro the preview as written
8. open PR & confirm that CI passes & request reviewers, if needed
9. act on any greptile review below a 5/5 score or leave comment explaining why you won't
10. delete this checklist section from the final squash commit before merging

📣 Summary

TODO

📖 Description

TODO

👷 Description for instance maintainers

TODO

💭 Notes

TODO

👀 Preview steps

1. ℹ️ have an account and a project
2. do this
3. do that
4. 🔴 [on main] notice that this isn't anywhere
5. 🟢 [on PR] notice that this is here
6. do that another thing
7. 🟢 notice that this changed like that

[greptile-apps]

Greptile Summary

This PR introduces test infrastructure and design documentation for the new React-based form builder, adding XlformAdapter as a thin wrapper around the legacy xlform serialization path, plus a comprehensive suite of unit tests covering question types, editing mutations, skip logic, translations, and structural nesting. The tsconfig.json gains resolveJsonModule: true to allow fixture JSON imports in tests.

• adapter.ts wraps dkobo_xlform.model.Survey with a typed load/serialize interface; its serialize() logic is also reimplemented in __tests__/helpers.ts, so most tests bypass the adapter class entirely.
• DESIGN_REFERENCE.md is a detailed architecture document covering the API contract, xlform internals, serialization quirks, and open design questions for the replacement implementation.
• The PR description still contains only the template-generated "TODO" placeholders in every section; the checklist is unchecked and the title does not follow the required <type>(<scope>): <title> DEV-XXXX format.

Confidence Score: 4/5

Safe to merge; changes are additive (docs and tests only) and do not touch any production runtime path.

The new test suite and design doc are purely additive — no production code is modified beyond adding adapter.ts and the tsconfig resolveJsonModule flag. The main concern is that tests/helpers.ts re-implements the XlformAdapter serialization logic independently, meaning most tests exercise the helper copy rather than the adapter class itself. The PR description also retains all TODO placeholders and an unconventional title, suggesting it is still a draft.

jsapp/js/formBuilder/tests/helpers.ts — its load/serialize logic is a copy of adapter.ts rather than a delegation, which quietly orphans the adapter from test coverage.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph TestInfra["Test Infrastructure"]
        H["__tests__/helpers.ts\n(loadSurvey, serialize, addRow, ...)"]
        A["formBuilder/adapter.ts\nXlformAdapter"]
    end

    subgraph FeatureTests["Feature Tests"]
        E["editing.tests.ts"]
        SL["skip-logic.tests.ts"]
        TR["translations.tests.ts"]
        N["nesting.tests.ts"]
        R["required.tests.ts"]
        C["constraint.tests.ts"]
    end

    subgraph QTypeTests["Question-Type Tests"]
        TXT["text.tests.ts"]
        SEL["select-one.tests.ts"]
        SOFF["select-one-from-file.tests.ts"]
        IMG["image.tests.ts"]
        RNG["range.tests.ts"]
        CALC["calculate.tests.ts"]
        DL["default-labels.tests.ts"]
        GRP["group.tests.ts"]
    end

    subgraph Core["xlform Core (CoffeeScript)"]
        XF["dkobo_xlform.model.Survey\n(loadDict / toJSON)"]
        FBU["formBuilderUtils.ts\n(surveyToValidJson,\nunnullifyTranslations)"]
    end

    H -->|uses directly| XF
    H -->|uses| FBU
    A -->|wraps| XF
    A -->|uses| FBU

    E --> H
    SL --> H
    TR --> H
    C --> H
    TXT --> H
    SEL --> H
    SOFF --> H
    IMG --> H
    RNG --> H
    CALC --> H
    DL --> H
    GRP --> H

    N --> A
    R --> A
    R --> H

Loading

_{Reviews (1): Last reviewed commit: "Initial work" | Re-trigger Greptile}

[greptile-apps]

Dangling reference to non-existent file

The comment references SERIALIZATION_QUIRKS.md, but that file does not exist anywhere in the repository — only DESIGN_REFERENCE.md was added in this PR. Any developer following the cross-reference will hit a dead end. Either the file needs to be created, or the comment should point to the relevant section of DESIGN_REFERENCE.md instead.

[greptile-apps]

Test helpers duplicate XlformAdapter logic, leaving the adapter uncovered

helpers.ts re-implements loadSurvey and serialize independently of XlformAdapter. Most tests (editing, skip-logic, translations, constraint, and all question-type tests) import from helpers, so they exercise this copy-pasted path rather than the actual XlformAdapter.serialize() in adapter.ts. If the adapter's serialization logic diverges in a future change, all those tests will continue to pass while the real adapter silently breaks. Only nesting.tests.ts and required.tests.ts use XlformAdapter directly. Consider having the helpers delegate to XlformAdapter to keep a single source of truth.

[greptile-apps]

PR description and title do not follow the repository template

Every section of the PR description (📣 Summary, 📖 Description, 👷 Description for instance maintainers, 💭 Notes, 👀 Preview steps) still contains the placeholder "TODO", the checklist has no items checked, and the PR title (add documentation and tests for form builder functionality DEV-2268) does not follow the required <type>(<scope>): <title> DEV-XXXX format. Please fill in or delete each section before merging, as required by the team's template.

Rule Used: What: PR descriptions must follow the repository's... (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!