lforms 29.3.1 → 33.2.0

package/CHANGELOG.md

@@ -2,6 +2,262 @@
 
 This project follows [Semantic Versioning](http://semver.org/).
 
+## [33.2.0] 2022-01-06
+### Added
+- Added a template option to control whether to display scores along 
+  with texts for answers that have scores.
+
+## [33.1.2] 2022-12-23
+### Fixed
+- FHIR Expressions were being run on form load once per item with an
+  autocompletion list.  It now will only run an extra time (on form load) once
+  for each item of type quantity which has a unit list, which is still more
+  often that should be needed, but this fix by itself should help speed up the
+  loading of many forms.
+
+## [33.1.1] 2022-12-13
+### Fixed
+- Fixed a bug that hidden items in a questionnaire are displayed when
+  a questionnaire response is loaded/merged into the questionnaire.
+
+## [33.1.0] 2022-11-30
+### Added
+- Added support for answerExpression on items whose types are string, integer,
+  date and time.
+### Fixed
+- Fixed a configuration issue in webpack dev server that FHIR js files
+  failed to load through a proxy in dev mode.
+
+## [33.0.0] 2022-11-15
+### Updated
+- Updated angular from v12 to v14
+### Changed
+- Removed the support for IE 11.
+- Only ES2017 files (no ES5 files) are in the build files.
+  The concatnated js file name is now lhc-forms.js, not
+  lhc-forms.es5.js or lhc-forms.es2015.js
+- Made item.dataType in lforms internal format required (a breaking change).
+- Made initial[x] values and the initialSelected on answerOption both work
+  when the item.type is choice or open-choice.
+### Added
+- Added support for string, date, time and integer values in answerOption (R4)
+  and option (STU3), including the support for related extensions (optionPrefix,
+  ordinalValue, and itemControl) and the initial[x] values.
+### Fixed
+- Fixed a bug in a custom cypress command.
+- Fixed a bug in importing a DiagnosticReport resource.
+
+## [32.2.3] 2022-11-03
+### Fixed
+- When running e2e tests, webpack-dev-server now serves the files so that
+  changes to source files are more quickly recompiled and updated for the test
+  runner.
+
+## [32.2.2] 2022-10-25
+### Fixed
+- Fixed a bug in the construction of the URL for a FHIR ValueSet $expand
+  operation, though there was already a work-around in place, so the only result
+  was a single failed network call logged to the console (which then can cause a
+  problem for Cypress tests).
+### Updated
+- Cypress has been updated to version 10.
+
+## [32.2.1] 2022-10-20
+### Fixed
+- Fixed a bug that enableWhen does not work on the values calculated from FHIRPath
+  expressions.
+
+## [32.2.0] 2022-10-18
+### Added
+- Added support the currenly published URI for the preferred terminology server
+  extension, though that URI will be changing
+  (https://jira.hl7.org/browse/FHIR-23977).
+
+## [32.1.0] 2022-09-18
+### Added
+- Added support the entryFormat extension
+
+## [32.0.3] 2022-09-12
+### Changed
+- Removed item._modifiedAnswers and use item.answers directly.
+- Removed fast-deep-equal package that is causing failed e2e tests in cypress.
+### Fixed
+- Fixed a bug that a user typed value on open-choice item is not set as a string value.
+
+## [32.0.2] 2022-09-07
+### Fixed
+- Moved the URI for the custom FHIR extension lforms generates to store
+  the "externallyDefined" setting out of the HL7 namespace.
+- Minor refactoring of the SDC import code, which should not impact users,
+  except that for STU3 item.definition will no longer be lost if you convert to
+  LForms format and and back to FHIR.  (The R4 import did not have that issue.)
+
+## [32.0.1] 2022-08-31
+### Fixed
+- Updated fhirpath.js to 3.0.0 to get a fix for
+  https://github.com/lhncbc/lforms/issues/102
+
+## [32.0.0] 2022-08-30
+### Changed
+- Removed a feature in which the autocompletion list fields would default to
+  the answer list value if there were just one answer in the list.
+- Changed the implementation on how the data changes in questionnaire data are handled.
+- Added the active row indicator for the radio buttons and checkboxes.
+
+## [31.0.1] 2022-08-26
+### Fixed
+- A very minor fix to the formatting of the form title, probably not visible to
+  a user, but which was causing a test to fail in another package.
+
+## [31.0.0] 2022-08-04
+### Changed
+- FHIR Quantities with a comparator can no longer be stored or loaded into a
+  Questionnaire.  This change is in line with
+  https://jira.hl7.org/browse/FHIR-37468.
+### Fixed
+- Fixes for handling Quantities in expressions.
+
+## [30.4.2] 2022-07-07
+### Changed
+- Added a button on the test page (test/pages/lforms_testpage.html) to batch convert lforms
+  to FHIR questionnaires or vice versa, where both input and output are zip files
+
+## [30.4.1] 2022-06-24
+### Fixed
+- Fixed a bug that FHIRPath expressions are not calculated on newly added
+  repeating items.
+- Fixed a bug that enableWhen is not working on prepopulated answers.
+
+## [30.4.0] 2022-06-13
+### Added
+- The beginnings of support to show error messages for individual fields.
+
+## [30.3.0] 2022-05-19
+### Added
+- Added support for answerOption.initialSelected in R4 Questionnaire
+
+## [30.2.0] 2022-05-18
+### Changed
+- Updated angular to v12 and ng-zorro-antd to v12.
+
+## [30.1.7] 2022-05-17
+### Fixed
+- Fixed a bug that the radio button of "Other" of the CWE typed items lost
+  its checked state when users typed in the input field.
+
+## [30.1.6] 2022-05-02
+### Fixed
+- Off-list string values from an open-choice field are now usable in an
+  expression for another open-choice field.
+
+## [30.1.5] 2022-04-22
+### Fixed
+- Support for multiple values coming from intialExpression or calculateExpresion
+  on fields that are of type string or coding.
+
+## [30.1.4] 2022-04-20
+### Fixed
+- Fixed a bug that the initial value of boolean type was not imported correctly
+  when it was false.
+
+## [30.1.3] 2022-04-04
+### Changed
+- Adjusted the styles of readonly items
+
+## [30.1.2] 2022-03-30
+### Fixed
+- Fixed a bug that observations were extracted from items that were either hidden or
+  had no values.
+- Fixed a bug that boolean value false was not extracted correctly.
+
+## [30.1.1] 2022-03-30
+### Fixed
+- Fixed a performance issue in the initial loading of a Questionnaire when it
+  contains a lot of choice and/or open-choice items.
+- Fixed a bug that the values of date or dateTime items in a repeating group
+  are not checked when adding a new repeating group.
+- Fixed a style issue for the first item in a group.
+
+## [30.1.0] 2022-03-25
+### Added
+- Added options to hide tree line styles, indentation or repetition numbers.
+
+## [30.0.1] 2020-03-22
+### Fixed
+- Fixed answerExpression and calculatedExpression processing so that for list
+  fields, both answers and answer lists can be set by an expression that depends
+  on the answers of another field.
+
+## [30.0.0] 2020-03-08
+Official release of the new Web Component version of lforms. See a list of changed 
+features in changed-features.md.
+### Fixed
+- Fixed a minor style issue
+### Changed
+- Code refactoring and clean up.
+- Made most commands in package.json work on Windows.
+
+
+## [30.0.0-beta.9] 2022-02-24
+### Fixed
+- Fixed a bug that the user saved data was overwritten by the values from initialExpression.
+### Changed
+- Added back the support of a CSS selector as the element parameter for LForms.Util functions
+  such as getFormData, getUserData and getFormFHIRData.
+- Removed the redundant resourceType parameter in the LForms.Util.mergeFHIRDataIntoLForms function.
+
+## [30.0.0-beta.8] 2022-02-17
+### Fixed
+- Fixed a bug that saved user data in a form are lost when answer lists are updated
+  by FHIRPath expression.
+
+## [30.0.0-beta.7] 2022-02-17
+### Added
+- Support for the newer launchContext "name" data type, valueCoding.  For
+  backward compatibility, valueId is still supported.
+  (https://build.fhir.org/ig/HL7/sdc/StructureDefinition-sdc-questionnaire-launchContext.html)
+
+## [30.0.0-beta.6] 2022-02-15
+### Added
+- Support for arbitrary launchContext names and resource types.  A second
+  parameter has been added to LForms.Util.setFHIRContext which is a map between
+  launchContext variable names and FHIR resource instances (as objects).  This
+  allows an application that is familiar with a partictular Questionnaire
+  to pass in the needed resources.
+
+## [30.0.0-beta.5] 2022-02-09
+### Fixed
+- Fixed a a bug that repeating rows in horizontal table (gtable) are not added
+  at the end of the table.
+### Added
+- Added the support of the questionnaire-hidden extension on the horizontal tables
+  (gtable) and the matrix (table).
+
+## [30.0.0-beta.4] 2022-02-04
+### Fixed
+- calculatedExpression no longer forces fields to be read-only.
+
+## [30.0.0-beta.3] 2022-01-25
+### Added
+- Added an onError event, that returns an error when FHIR resources
+  fail to load, or when there is an exception during the initialization.
+- Added cypress for e2e tests.
+
+## [30.0.0-beta.2] 2022-01-10
+### Changed
+- Removed locale files from moment.js
+- Code refactoring on the initial release.
+
+## [30.0.0-beta.1] 2021-12-15
+### Fixed
+- Fixed a style issue on items with a single unit.
+
+## [30.0.0-beta.0] 2021-12-10
+### Changed
+- Included the initial release of the Web Component version of the LHC-Forms
+  widget in the "next" directory. This will be reorganized out of the "next"
+  directory prior to the non-beta release.
+
 ## [29.3.1] 2021-10-20
 ### Fixed
 - If a form contained an attachment type question, hitting enter in another

package/README.md

@@ -1,38 +1,121 @@
 ## What is LForms?
 
 [LForms](http://lhncbc.github.io/lforms/), a.k.a. LHC-Forms, is a feature-rich,
-open-source widget that creates input forms, based on definition files, for
-Web-based applications.  In addition to its native form-definition format, it
-partially supports the HL7 FHIR Questionnaire standard (SDC profile), and work
+open-source Web Component that creates input forms, based on definition files, 
+for Web-based applications. In addition to its native form-definition format, 
+it partially supports the HL7 FHIR Questionnaire standard (SDC profile), and work
 is in progress to expand that support.
 
 It is being developed by the Lister Hill National Center for Biomedical
 Communications ([LHNCBC](https://lhncbc.nlm.nih.gov)), National Library of
 Medicine ([NLM](https://www.nlm.nih.gov)), part of the National Institutes of
-Health ([NIH](https://www.nih.gov)), with the collaboration and support from the
-[Regenstrief Institute](https://www.regenstrief.org/), Inc. and the
+Health ([NIH](https://www.nih.gov)), with the collaboration and support from 
+the [Regenstrief Institute](https://www.regenstrief.org/), Inc. and the
 [LOINC](https://loinc.org/) Committee.
 
 For features and demos, please visit the [project
 page](http://lhncbc.github.io/lforms/).
 
 ## Licensing and Copyright Notice
+
 See [LICENSE.md](LICENSE.md).
 
 ## Customizing and Contributing
+
 If you wish to revise this package, the following steps will allow you to make
 changes and test them:
 
-* Install Node.js (version 10 is what we are currently using, but it should work with later versions)
-* Clone the lforms repository and cd to its directory
-* npm ci
-* Make sure node_modules/.bin is in your path
-* bower install
-* npm run build
-* npm run start # starts the app we use for testing
-* npm run test # runs the tests
-* Templates are in app/views; CSS in app/styles
+- Install Node.js (version 14 is what we are currently using, but it should work 
+  with later versions)
+- Clone the lforms repository and cd to its directory
+- `source bashrc.lforms` (make sure node dir is available at ~/)
+- `npm ci`
+- `source bashrc.lforms` # to add node_modules/.bin to your path
+- `npm run build` # build both FHIR libs and LHC-Forms web component
+- `npm run start` # starts the app we use for testing
+- `npm run test` # runs the unit tests and e2e tests
 
 If you are planning to contribute new functionality back to us, please
 coordinate with us, so that the new code is in the right places, and so that
 you don't accidentally add something that we are also working on.
+
+## Development server
+
+- Run `npm run start` for a dev server. Navigate to `http://localhost:4200/`.
+  The app will automatically reload if you change any of the source files.
+
+- Run `npm run start-public` if you need to access to the dev server from a 
+  different machine. For example, to run Narrator from a Windows PC.
+
+## Build
+
+- Run `npm run build` to build the project and generate a production version of
+  the js files, which are much smaller than the development version. It
+  generates an ES2017 version of the js files under dist/lforms. For details on
+  the files to load, see ["Usng the LHC-Forms Web Component"](#using).  
+  The `dist` directory is deleted and recreated during the process.
+
+  The build also concatenates all the js files (except for zone.min.js and the
+  FHIR support files) into a single `lhc-forms.js` file, and it works,
+  but we don't currently recommend their use because the
+  source maps don't work with these files. Also, there is a dist/webcomponent
+  directory that is created with a copy of the files in dist/lforms, but that
+  is only needed for the tests.
+
+## Running tests
+
+1. Run `npm run test` to run unit tests and e2e tests, which also copies the 
+   FHIR lib files and built files in places for testing.
+
+## Running unit tests
+
+1. Run `npm run test:unit` to execute the unit tests via 
+   [Karma](https://karma-runner.github.io).
+
+## Running end-to-end tests
+
+1. Run `npm run test:e2e` to execute the end-to-end tests via 
+   [Cypress](https://www.cypress.io/). The e2e tests are configured to use Chrome.
+
+## <a id="using">Using the LHC-Forms Web Component</a>
+
+There are several script files to load. If you are building this, these files 
+will be under `dist/lforms`. If you are using the pre-built versions from
+https://clinicaltables.nlm.nih.gov/lforms-versions, then the file paths below
+are relative to those versioned directories.
+
+1. `webcomponent/styles.css`
+
+You need to include the following files in your project:
+
+1. `webcomponent/styles.css`
+2. `webcomponent/assets/lib/zone.min.js` (unless you already have zone.min.js 
+   on the page)
+3. `webcomponent/scripts.js`
+4. `webcomponent/runtime.js`
+5. `webcomponent/polyfills.js`
+6. `webcomponent/main.js`
+7. _One_ of the FHIR support library files, assuming you are planning to use
+   FHIR Questionnaires:
+   - `fhir/lformsFHIRAll.min.js`
+   - `fhir/R4/lformsFHIR.min.js`
+   - `fhir/STU3/lformsFHIR.min.js`
+
+There is an example of an app using these files at
+https://lhcforms.nlm.nih.gov/lforms-fhir-app/.
+For details about how to work with this library, and for information about an
+announcements list, see the [documentation](https://lhncbc.github.io/lforms/).
+
+## <a id="npm-package">lforms npm package</a>
+
+A complete npm package that you can use with import/require statements in your
+code is not ready yet. The current lforms npm package only contains built files
+in `/dist/lforms` directory. You can use those files as described in above
+section [Using the LHC-Forms Web Component](#using).
+
+## <a id="docs">Related Documents</a>
+- `form_definition.md` The internal data format of the LHC-Forms widget.
+- `changed-features.md` The list of features that changes between the new 
+version (v30.0.0) and previous versions.
+- `r4-support.md` The FHIR R4 features supported by LHC-Forms widget. 
+- `sdc-support.md` The FHIR SDC features supported by LHC-Forms widget.

package/changed-features.md

@@ -0,0 +1,99 @@
+## New features in version 30.0.0
+* **Web Component** The new LHC-Forms is a Web Component widget created with angular. 
+  It is no longer developed with angularjs.
+  #### **Web Component Properties:**
+  * **questionnaire** - A JSON object of a FHIR Questionnaire (including FHIR SDC Questionnaire),
+ or the above LHC-Forms internal format.
+  * **options** - Optional, a JSON object. The options defined in [templateOptions](#templateOptions).
+  * **prepop** - Optional, a boolean value. A flag indicating whether to run the pre-populate operation
+ for the FHIR Questionnaire. The default value is false.
+  * **fhirVersion** - Optional, a string value. The specified FHIR version of the data provided in 
+ 'questionnaire'. If this is not provided, a FHIR version will be determined from 
+ the 'questionnaire'. The supported FHIR versions are 'R4' and 'STU3'.
+
+  #### **Emitted Events:**
+
+  * **onFormReady** - emitted when the form is fully initialied, and FHIRPath expressions
+ are run if any, data are pre-populated if any, and the form is ready for user interactions. 
+ No data is returned in this event.
+
+  #### **How to use properties and events:**
+  * In HTML: 
+```
+        <wc-lhc-form id='test-form'></wc-lhc-form>
+```
+  * JavaScript Code: 
+```
+        lhcFormWidget = document.getElementById('test-form'); 
+        lhcFormWidget.questionnaire = aQuesionnaire;
+        ...
+        lhcFormWidget.addEventListener('onFormReady', e => {
+          // do something
+          ...
+        });
+```
+
+## Features not supported in version 30.0.0
+* **AngularJS Directive** The new LHC-Forms does not includes an AngujarJS directive.
+
+* **templateOptions** - The following options within templateOptions are not supported:
+  * showColumnHeaders - a boolean that controls whether to show the header row
+      with the "Name", "Value", and "Unit" column labels.  The default is true.
+  * showQuestionCode - a boolean that controls whether to show question codes.
+      The default is false.
+  * tabOnInputFieldsOnly - a boolean that controls whether to control TAB keys
+      to stop on the input fields only (neither buttons, nor units fields).
+      The default is false.
+  * hideFormControls - a boolean that controls whether to hide the controls section
+      on top of the form. The default is true.
+  * hideUnits - a boolean that controls whether to all the Units column to
+      be hidden from the data table. The default is false.
+  * showFormOptionPanel - a boolean that controls whether to show the option panel
+      that displays all the form options.
+  * showFormOptionPanelButton - a boolean that controls whether to show the button
+      next to the form title that hides/shows the form options panel.
+  * useAnimation - a boolean that controls whether to use animation on the form.
+      The default is true.
+  * <a name="showFormHeader"></a>showFormHeader - a boolean that controls whether to
+      show a row fields above the actual form like "Date Date", "Comment", etc.
+      The default is false.
+  * formHeaderItems - an array defining fields above the form (see
+      [showFormHeader](#showFormHeader)).  If you omit templateOptions, a default will be
+      provided which will have the fields "Date Done", "Time Done", "Where
+      Done", and "Comment". If you wish to specify your own definitions,
+      a complete array should be provided where each
+      element in the array should be a hash with the following keys:
+        * question - the field label
+        * dataType - the kind of field.  This can be DT for a date field with a
+          calender widget, ST for a normal input field, CNE for a list field in
+          which values are required to match the list, or CWE for a list field in
+          which values can be off the list.
+        * answers - For data types CNE or CWE, this is an array with the list
+          data.  Each element in the array is a hash with the following keys:
+          * text - the display string for the list item
+          * code - (optional) a code that identifies the list item
+        * displayControl - This controls display styles of the column or the field.
+          It is a hash with the keys of "colCSS" for columns styles and "css" for field
+          styles. The values are an array of hashes of valid CSS styles. Here is an example:
+          `{"colCSS": [{"name":"width","value":"30%"},{"name":"min-width","value":"4em"}]}`
+        * <a name="answerCardinality"></a>answerCardinality - For lists, this
+          allows you to control whether list is multi-select or not.  It is a hash
+          that takes two keys, "min" and "max".  If you "min" to "1", then the
+          user will be required to provide an answer.  If you set "max" to "*",
+          the list becomes multi-select.  (Other possibilities are not yet
+          supported.)
+
+* **Emitted (AngularJS) Events**
+
+  * **LF_EVENT_REPEATING_ITEM_ADDED** - emitted when a repeatable item or section is added to the form by clicking
+  the "add" button. An event attr object is associated with the event, with the following fields:
+    * event - the event name, 'LF_EVENT_REPEATING_ITEM_ADDED'
+    * formId - the code of the form
+    * itemId - the _elementId of the newly added item or section
+    * time - the time stamp when the event happens
+  * **LF_EVENT_REPEATING_ITEM_DELETED** - emitted when a repeatable item or section is deleted from the form by clicking
+ the "delete" button. The event attr object has the same set of the fields:
+    * event - the event name, 'LF_EVENT_REPEATING_ITEM_DELETED'
+    * formId - the code of the form
+    * itemId - the _elementId of the item or section that has just been deleted.
+    * time - the time stamp when the event happens

package/dist/lforms/LICENSE.md

@@ -0,0 +1,70 @@
+# LICENSE
+
+Licensing and Copyright Notice and Terms of Use
+
+Owner Notice: This software (including any associated website-service or
+downloadable source (code) was developed by the Lister Hill National Center
+for Biomedical Communications (LHNCBC), a research and development division
+of the U.S. National Library of Medicine (NLM), with the permission and based
+on the copyrighted content of the Regenstrief Institute.
+
+This material may contain content from LOINC ® (http://loinc.org). The
+LOINC table, LOINC codes, LOINC panels and forms file, LOINC linguistic variants
+file, LOINC/RSNA Radiology Playbook, and LOINC/IEEE Medical Device Code Mapping
+Table are copyright © 1995-2016, Regenstrief Institute, Inc. and the
+Logical Observation Identifiers Names and Codes (LOINC) Committee and is
+available at no cost under the license at http://loinc.org/terms-of-use.
+LOINC ® is a registered United States trademark of Regenstrief Institute, Inc.
+
+If LOINC content is included, this software is distributed under the conditions
+set forth at https://loinc.org/terms-of-use and the following terms and conditions.
+
+If this product includes all or a portion of the UCUM table, UCUM codes, and
+UCUM definitions or is derived from it, it is subject to a license from
+Regenstrief Institute, Inc. and The UCUM Organization. Your use of the UCUM table,
+UCUM codes, UCUM definitions also is subject to this license, a copy of which is
+available at http://unitsofmeasure.org. The current complete UCUM table, UCUM
+Specification are available for download at http://unitsofmeasure.org. The UCUM
+table and UCUM codes are copyright © 1995-2009, Regenstrief Institute, Inc.
+and the Unified Codes for Units of Measures (UCUM) Organization. All rights reserved.
+
+If UCUM content is included, this software is distributed under the conditions
+set forth at http://unitsofmeasure.org/trac/wiki/TermsOfUse and the following
+terms and conditions.
+
+The following terms and conditions are based on the BSD open-source license.
+
+If publishing research that used this software, please include a citation that
+acknowledges it.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted for commercial and non-commercial purposes and products alike,
+provided that the following conditions are met:
+
+  * Redistributions of source code shall retain the above Owner Notice, this
+  list of conditions and the following disclaimer, and display them prominently.
+  * Redistributions in binary form shall prominently reproduce the above Owner
+  Notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+  * Neither the names of the National Library of Medicine (NLM), the Lister
+  Hill National Center for Biomedical Communications (LHNCBC), the National
+  Institutes of Health (NIH), nor the names of any of the software contributors
+  may be used to endorse or promote products derived from this software without
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE OWNER AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+SHALL THE OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+THE UCUM TABLE (IN ALL FORMATS), UCUM DEFINITIONS, AND SPECIFICATION ARE
+PROVIDED "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES ARE DISCLAIMED, INCLUDING,
+BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE.
+

package/dist/lforms/README.md

@@ -0,0 +1,100 @@
+## What is LForms?
+
+[LForms](http://lhncbc.github.io/lforms/), a.k.a. LHC-Forms, is a feature-rich,
+open-source Web Component that creates input forms, based on definition files, for
+Web-based applications. In addition to its native form-definition format, it
+partially supports the HL7 FHIR Questionnaire standard (SDC profile), and work
+is in progress to expand that support.
+
+It is being developed by the Lister Hill National Center for Biomedical
+Communications ([LHNCBC](https://lhncbc.nlm.nih.gov)), National Library of
+Medicine ([NLM](https://www.nlm.nih.gov)), part of the National Institutes of
+Health ([NIH](https://www.nih.gov)), with the collaboration and support from the
+[Regenstrief Institute](https://www.regenstrief.org/), Inc. and the
+[LOINC](https://loinc.org/) Committee.
+
+For features and demos, please visit the [project
+page](http://lhncbc.github.io/lforms/).
+
+## Licensing and Copyright Notice
+See [LICENSE.md](LICENSE.md).
+
+## Customizing and Contributing
+If you wish to revise this package, the following steps will allow you to make
+changes and test them:
+
+* Install Node.js (version 14 is what we are currently using, but it should work with later versions)
+* Clone the lforms repository and cd to its directory
+* `source bashrc.lforms` (make sure node dir is available at ~/)    
+* `npm ci`
+* `source bashrc.lforms` # to add node_modules/.bin to your path
+* `npm run build` # build both FHIR libs and LHC-Forms web component
+* `npm run start` # starts the app we use for testing
+* `npm run test` # runs the unit tests and e2e tests
+
+If you are planning to contribute new functionality back to us, please
+coordinate with us, so that the new code is in the right places, and so that
+you don't accidentally add something that we are also working on.
+
+## Development server
+
+* Run `npm run start` for a dev server. Navigate to `http://localhost:4200/`. 
+   The app will automatically reload if you change any of the source files.
+
+* Run `npm run start-public` if you need to access to the dev server from a different machine. 
+   For example, to run Narrator from a Windows PC.
+
+## Build
+
+* Run `npm run build` to build the project and generate a production version of
+  the js files, which are much smaller than the development version. It
+  generates an ES2017 version of the js files under dist/lforms. For details on 
+  the files to load, see ["Usng the LHC-Forms Web Component"](#using).  
+  The `dist` directory is deleted and recreated during the process. 
+  
+  The build also concatenates all the js files (except for zone.min.js and the
+  FHIR support files) into a single `lhc-forms.js` file, and it works, 
+  but we don't currently recommend their use because the
+  source maps don't work with these files.  Also, there is a dist/webcomponent
+  directory that is created with a copy of the files in dist/lforms, but that
+  is only needed for the tests.
+
+## Running tests
+1. Run `npm run test` to run unit tests and e2e tests, which also copies the FHIR lib files 
+   and built files in places for testing.
+
+## Running unit tests
+
+1. Run `npm run test:unit` to execute the unit tests via [Karma](https://karma-runner.github.io).
+
+## Running end-to-end tests
+
+1. Run `npm run test:e2e:prepare` to copy necessary files in places for the tests and to update the web driver.
+
+1. Run `npm run test:e2e` to execute the end-to-end tests via [Cypress](https://www.cypress.io/). 
+   The e2e tests is configured to use Chrome. 
+
+## <a id="using">Using the LHC-Forms Web Component</a>
+There are several script files to load.  If you are building this, these files will be
+under `dist/lforms`.  If you are using the pre-built versions from
+https://clinicaltables.nlm.nih.gov/lforms-versions, then the file paths below
+are relative to those versioned directories.
+1. `webcomponent/styles.css`
+
+You need to include the following files in your project: 
+1. `webcomponent/styles.css`
+2. `webcomponent/assets/lib/zone.min.js` (unless you already have zone.min.js on the page)
+3. `webcomponent/scripts.js`
+4. `webcomponent/runtime.js`
+5. `webcomponent/polyfills.js`
+6. `webcomponent/main.js`
+7. *One* of the FHIR support library files, assuming you are planning to use
+   FHIR Questionnaires:
+   * `fhir/lformsFHIRAll.min.js`
+   * `fhir/R4/lformsFHIR.min.js`
+   * `fhir/STU3/lformsFHIR.min.js`
+
+There is an example of an app using these files at
+https://lhcforms.nlm.nih.gov/lforms-fhir-app/.
+For details about how to work with this library, and for information about an
+announcements list, see the [documentation](https://lhncbc.github.io/lforms/).