Uplift to use cht-form web component

jkuester commented 11 months ago

So, let me start with a profuse apology for the size of this PR. There just was not really any way to do this incrementally since this is basically shifting some fundamental things with regard to how the cht-core resources are consumed within the Test Harness.

I am very aware that I have made a ton of design decisions (big and small) all on my own here that may or may not be acceptable to the project maintainers. :sweat: I consider this PR to be more of a "production ready" proof-of-concept to show how the integration could be done. I am exploring a lot of new ground here, and have something that seems to work pretty well, but I welcome any and all ideas on better ways to approach this!

Overview

The goal of this PR is to support depending on the latest version of code from cht-core by leveraging the new cht-form functionality for rendering forms. (Previously we were blocked from depending directly on logic in cht-core/webapp since it is TS code written for Angular. The cht-form web component allows us to extract this logic into html/js/css resources that the harness can depend on directly.) As a part of adjusting the dependency approach, I have sought to bring back the ability to target multiple different versions of cht-core code from the same version of the Test Harness (though this will only be available for future versions of the CHT).

Build tree

I have created this diagram to try and make it easier to understand how the various pieces and files fit together. Everything in this diagram outside the build directory gets committed to the repo. The dist/form-host.dev.js and the dist/all-chts-bundle.dev.js files are rebuilt every time the build.sh script is run, but the various artifacts inside the dist/cht-core-x-x directories are only (re)built as needed.

flowchart TD
    subgraph cht-bundles
        cht-bundles/all-chts-bundle.js[all-chts-bundle.js]
        subgraph cht-bundles/cht-core-4-6
            cht-bundles/cht-core-4-6/bundle.js[bundle.js]
            cht-bundles/cht-core-4-6/xsl-paths.js[xsl-paths.js]
        end
    end
    subgraph build
        subgraph build/cht-core-4-6[cht-core-4-6]
            build/cht-core-4-6/cht-form[build/cht-form]
            build/cht-core-4-6/ddocs[ddocs]
            build/cht-core-4-6/api/src/xsl[api/src/xsl]
        end
        build/cht-core-4-6-ddocs.json[cht-core-4-6-ddocs.json]
    end
    subgraph dist
        dist/all-chts-bundle.dev.js[all-chts-bundle.dev.js]
        dist/form-host.dev.js[form-host.dev.js]

        subgraph dist/cht-core-4-6
            dist/cht-core-4-6/cht-core-bundle.dev.js[cht-core-bundle.dev.js]
            dist/cht-core-4-6/cht-form.js[cht-form.js]
            dist/cht-core-4-6/xsl[xsl]
        end

    end
    subgraph src
        src/harness.js[harness.js]
        subgraph src/form-host[form-host]
            src/form-host/index.js[index.js]
            src/form-host/form-host.html[form-host.html]
        end
    end

    build/cht-core-4-6 --> cht-bundles/cht-core-4-6/bundle.js
    build/cht-core-4-6/api/src/xsl --> dist/cht-core-4-6/xsl
    build/cht-core-4-6/ddocs -->|compile-ddocs.js| build/cht-core-4-6-ddocs.json

    cht-bundles/all-chts-bundle.js -->|webpack.config.js| dist/all-chts-bundle.dev.js
    dist/cht-core-4-6/cht-core-bundle.dev.js --> cht-bundles/all-chts-bundle.js
    dist/cht-core-4-6/xsl --> cht-bundles/cht-core-4-6/xsl-paths.js

    build/cht-core-4-6-ddocs.json --> cht-bundles/cht-core-4-6/bundle.js
    cht-bundles/cht-core-4-6/bundle.js -->|cht-bundles/webpack.config.cht-core.js| dist/cht-core-4-6/cht-core-bundle.dev.js
    cht-bundles/cht-core-4-6/xsl-paths.js -->|cht-bundles/webpack.config.cht-core.js| dist/cht-core-4-6/cht-core-bundle.dev.js

    build/cht-core-4-6/cht-form -->|cht-bundles/webpack.config.cht-core.js| dist/cht-core-4-6/cht-form.js

    src/form-host/index.js -->|webpack.config.js| dist/form-host.dev.js
    dist/form-host.dev.js --> src/form-host/form-host.html
    dist/cht-core-4-6/cht-form.js --> src/form-host/form-host.html

    dist/all-chts-bundle.dev.js --> src/harness.js
    src/form-host ----> src/harness.js

Details

Recent changes to the cht-core repository make it difficult (impossible?) to have it listed as a dependency in the package.json (get errors when doing npm install). This is one of the reasons I switched to manually cloning the repo.
The main motivation for introducing the new cht-core-bundle.dev.js files was to avoid having to rebuild all CHT versions (contained in the all-chts-bundle.dev.js) just to add/update one of them. I have mild hopes that this might allow for longer-term support in the harness for particular CHT versions.
For what its worth, I do not believe that any of the font/icon files in the dist/cht-core-x-x directories are strictly necessary for the Test Harness to function (though removing them may affect how forms are displayed in the Project Explorer). Those are getting pulled over automatically by Webpack due to their usage in the css, but they should be pretty easy to exclude if we wanted to...
The most significant changes I had to make to the test harness logic were in the form-filler.js file where I changed the logic to be less tightly coupled to internal Enekto code and more able to just directly consume the content on the page.
For the Project Explorer, I have tried to take the most simple approach to integrating with cht-form.
- I think a lot more could be done in terms of making it look/work even better, but at least I don't think I have made it any worse!
- The main difference in behavior is that now there is some responsiveness based on the width of the browser window. If you make the window too narrow, it will switch into the "mobile" view for the form and hide the side-bar. This could be considered a feature, but as of yet there is no way to get back to the list of forms from this view.... :sweat_smile:

I am pretty sure this closes https://github.com/medic/cht-conf-test-harness/issues/138 and closes https://github.com/medic/cht-conf-test-harness/issues/204 (I guess this is as close as we get to 4.1). It might also make sense to say this addresses https://github.com/medic/cht-conf-test-harness/issues/46 as well since basically all the Enekto widgets should be functional at this point except for the db-object-widget (which is tracked separately in https://github.com/medic/cht-conf-test-harness/issues/184)...

jkuester commented 9 months ago

@kennsippell please add/redirect reviewers for this PR as makes sense!

This is not particularly urgent as it depends on the as of yet unreleased cht-core 4.6.0, but it will be required for running config tests against the new Enekto version coming in 4.6.0, so we don't want to wait too long here!

jkuester commented 6 months ago

@kennsippell this should be ready to merge/release at your convenience!

It looks like the release-notes have not been updated in awhile. I could not find an automated way to generate anything, so I made an attempt to manually pull something together based on the git commit history and the changes to the version in the package.json. I doubt it is perfect, but probably better than nothing.

medic-ci commented 6 months ago

:tada: This PR is included in version 1.0.0 :tada:

The release is available on:

Your semantic-release bot :package::rocket:

medic / cht-conf-test-harness