CHANGELOG.md

Change log

This log documents changes for the @aehrc/smart-forms-renderer. This project follows Semantic Versioning.

For changelogs of other libraries, please refer to their respective repositories under the /packages folder:

• SDC-Populate: /packages/sdc-populate/CHANGELOG.md
• SDC-Assemble: /packages/sdc-assemble/CHANGELOG.md
• SDC-Template-Extract: /packages/sdc-template-extract/CHANGELOG.md

Changelog only includes changes from version 0.36.0 onwards.

[1.5.0] - 2026-09-10

Added

• Added a headless engine entrypoint, published as @aehrc/smart-forms-renderer/engine, that re-exports the SDC engine - form lifecycle, QuestionnaireResponse construction/traversal, item inspection, answer parsing, repopulation and observation-based extraction - without pulling in Material UI, Emotion, react-dom or other DOM/UI dependencies. An exports map is now published covering every path the package previously exposed only via internal lib/... deep imports.
• Added i18n support for renderer-owned UI text ("chrome") and locale-aware, order-aware date formatting/validation (e.g. year-first locales correctly get YYYY/MM), configured via the existing rendererConfigStore's locale and rendererStrings options. Consuming apps supply their own translation catalogs; defaults remain unchanged (English, DD/MM/YYYY), so existing consumers are unaffected.
• Styled warning-level validation feedback (from targetConstraint violations and OperationOutcome issues) differently from errors - amber helper text with no red border - and exported useValidationFeedbackSeverity so consumers can act on feedback severity directly. useValidationFeedback is kept as a deprecated wrapper. See issue #1984

Fixed

• Fixed answerOption-based choice fields (Select, Autocomplete, Radio, Checkbox) showing raw codes, becoming unresponsive, or desyncing from the stored answer when a terminology $lookup fails or an option's display text changes. Options whose display cannot be resolved are now filtered out of the list with a single warning shown below the field, since raw codes are not acceptable in a clinician-facing UI, while a previously-answered option is preserved using its live or originally-recorded display instead of vanishing. Several related falsy-value (0, '') and key-collision matching bugs are also fixed. See issue #1931
• Fixed autocomplete choice fields showing "No options" while a terminology search is still below the debounce threshold, instead of a "Type to search..." prompt.
• Fixed repeating group validation errors displaying on every instance instead of only the invalid one - errors are now scoped by the instance's position within the QuestionnaireResponse, including when that position differs from the rendered row position (e.g. after a gtable row is deselected).
• Fixed clearing an autocomplete/choice field leaving a stale answer in the QuestionnaireResponse instead of removing it, and fixed repeat group instances/gtable rows not being removed when clearing their last answer left them empty.
• Fixed wrapped, multi-line question labels rendering below their field instead of beside it.

[1.4.0] - 2026-07-03

Added

• Instruction text (display items with questionnaire-displayCategory: instructions) is now programmatically associated with its parent input field via aria-describedby across all field types. Screen readers now announce the instruction text when the field receives focus, rather than requiring a separate tab to the instruction item. See issue #1640
• Added rendering of Questionnaire.title and item.prefix. Both now appear in the renderer, and support text styling via rendering-style, rendering-markdown, and rendering-xhtml extensions. Set hideQuestionnaireTitle: true in the renderer config to suppress the built-in title rendering.
• Added responseHasErrors to the QuestionnaireResponseStore. This is true when the response contains items with error or fatal severity — it does not consider warnings.
• Added item-level targetConstraint support. Constraints can now be defined directly on questionnaire items (not only at the questionnaire root), and are extracted and evaluated per-item.
• Added screen reader announcements for error messages in input fields via role='alert' and aria-live='assertive'. See issue #1745
• Improved responsive layout on large screens — the renderer now expands to fill available screen width, with per-item max-widths applied to keep individual inputs at a readable size. See issue #1936
• Added horizontal dividers between repeat group instances in RepeatGroupView.
• The remove button in repeat groups is now enabled even when only one instance remains, allowing users to clear pre-populated data. Removing the last instance leaves one blank instance in its place. See issue #1810

Fixed

• Fixed targetConstraint expression logic being inverted — per the FHIR spec, expressions should return true when the constraint is satisfied (valid). See issue #1954
• Fixed validation errors (required, targetConstraint) not surfacing on date and dateTime fields. These fields now correctly report constraint and required errors.
• Fixed date and dateTime fields not validating against minValue/maxValue constraints.
• Fixed repopulate dialog incorrectly showing unchanged repeat group items as modified after a user had deleted or reordered instances. The comparison was positional, so any shift in item index caused remaining items to appear as changed. Matching is now content-based. See issue #1940
• Fixed getResponse() and removeEmptyAnswers() stripping item.definition from returned QuestionnaireResponse items. See issue #1801
• Fixed selected value in choice select (autocomplete) fields appearing too far left due to missing padding. See issue #1842
• Fixed deeply nested repeat group content being pushed off-screen when zooming in, with no scrollbar to access it. Group items now scroll horizontally independently. See issue #1809
• Fixed validation feedback text not wrapping correctly in grid/table cells for autocomplete-based choice fields — it was rendered as a flex sibling of the input, compressing it into the remaining row space. Feedback now stacks below the input. Also fixes the missing error border on these fields when feedback is present.

[1.3.1] - 2026-03-25

Fixed

• Fixed accordion scroll position jumping when expanding accordion items. See issue #1796
• Fixed the sticky tab list overflowing the viewport on long forms. The tab list now dynamically constrains its height and becomes scrollable when needed.

[1.3.0] - 2026-03-11

Added

• Added tabListStickyTop option to the renderer store. When supplied, a tabbed form's tab menu will stick to the top of the page offset by this value, keeping it visible during scrolling.
• fhirContext references from SMART App Launch are now resolved and stored in the renderer SMART config, making them available for use in answerExpressions.

Fixed

• Conditionally display placeholder in select fields, fixing issue 1834

[1.2.14] - 2026-03-05

Changed

• Reduced vertical padding and margins to limit excessive whitespace in the renderer.
• Changed standalone autocomplete fields to be multiline so that value is not truncated.

Fixed

• Fixed regression causing some calculatedExpressions to not be displayed.

[1.2.13] - 2026-02-12

Fixed

• Fixed an issue where existing QuestionnaireResponse repeat group items were being overwritten by blank data when applying calculatedExpression values, causing issue #1811

[1.2.12] - 2026-01-13

Added

• Added support for text styling on answerOption.valueString.
• Improved keyboard-only navigation and screen reader accessibility for combobox dropdowns. See issue #1762

Fixed

• Fixed missing calculatedExpression sync animations on choice and open-choice items. See issue #1643
• Fixed regression in enableWhen initialisation that prevented some items from populating. See issues #1781 and #1775

[1.2.11] - 2025-10-28

Fixed

• Fixed an issue where enableWhen items are not initialising when a filled form is passed into buildForm().

[1.2.10] - 2025-10-28

Use 1.2.10 instead of 1.2.9 due to a publishing issue.

Fixed

• Add aria-hidden="true" to text-field based questions' clear button (x).

[1.2.9] - 2025-10-28

Fixed

• Add aria-hidden="true" to text-field based questions' clear button (x).

[1.2.8] - 2025-10-28

Fixed

• Required field asterisks accessibility enhancements also applies to group headings and tab buttons.

[1.2.7] - 2025-10-28

Fixed

• Required field asterisks are now properly announced as "Mandatory field" by screen readers. Refer to issue #1741

[1.2.6] - 2025-10-28

Fixed

• Remove openOnFocus prop from autocomplete fields to allow screen readers to read out label, placeholder text and control's role. Refer to issue #1733

[1.2.5] - 2025-10-28

Fixed

• Use deepEqual for checkbox answer matching instead of JSON.stringify equality to correctly compare valueCoding objects. Refer to issue #1738

[1.2.4] - 2025-10-28

Fixed

• Measurement units (e.g. cm, kg) are now associated with their input fields, ensuring screen readers correctly announce the unit when the field receives focus. Refer to issue #1641

[1.2.3] - 2025-10-27

Fixed

• Fixed bug with the rendering of the calculation animation on the first calculated expression update. Issue described here

[1.2.2] - 2025-10-27

Fixed

• Fixed bugs with the rendering and updating of nested items, within an item that is a repeat item. The issue is described here

[1.2.1] - 2025-10-27

Fixed

• Fixed valueSet promise resolution in buildForm stage to exclude answerValueSet urls from autocomplete items. This is because these urls are meant to be used alongside a filter parameter.
• Fixed renderer calcExp not working on open-choice and choice fields. Issue is described here
• Fixed renderer open-choice not retaining the selected option in calcExp. Issue is described here
• Changed renderer aria-label as per request described here

[1.2.0] - 2025-10-23

Added

• Added support for optional heading focus when switching tabs via disableHeadingFocusOnTabSwitch field in RendererConfigStore.

[1.1.0] - 2025-10-23

Added

• Added calcExpUpdated prop to overrideComponent interface.

Fixed

• Fixed accurate option highlighting in choice autocomplete items.

[1.0.0] - 2025-10-13

(WARNING: Major breaking changes with library API)

For smooth migration, a migration guide is provided at MIGRATION-v1.0.md.

Changed

buildForm, QuestionnaireStore and QuestionnaireResponseStore changes:

• buildForm() and useBuildForm() now accept a BuildFormParams object instead of multiple parameters.
• The additionalVariables parameter is replaced with additionalContext. Its usage remains the same - it is used to inject additional fhirPathContext variables.
• A new library function repopulateForm() is added to repopulate the form with a new QuestionnaireResponse and/or additionalContext while preserving the current Questionnaire state. Its parameters are defined in the interface RepopulateFormParams.

QuestionnaireStore and QuestionnaireResponseStore changes:

• If you were previously calling QuestionnaireStore.setPopulatedContext to inject populatedContext into the renderer, you no longer need to do so. buildForm(), useBuildForm() and repopulateForm() will take care of it for you via the additionalContext parameter.

• For pre-population/re-population, you do not need to call QuestionnaireStore.updatePopulatedProperties and QuestionnaireResponseStore.setUpdatableResponseAsPopulated anymore. Both of these functions are now removed. buildForm(), useBuildForm() and repopulateForm() will take care of it for you.

  - // Remove these lines
  - const updatedResponse = await updatePopulatedProperties(populatedResponse, populatedContext);
  - setUpdatableResponseAsPopulated(updatedResponse);
  -
  - if (populatedContext) {
  -   setPopulatedContext(populatedContext, true);
  - }
  
  + // Re-run buildForm (or repopulateForm) with the new populatedResponse
  + await buildForm({
  +   questionnaire: sourceQuestionnaire,
  +   questionnaireResponse: populatedResponse,
  +   terminologyServerUrl: defaultTerminologyServerUrl,
  +   additionalContext: populatedContext
  + });
  

• QuestionnaireStore.populatedContext and QuestionnaireStore.setPopulatedContext are replaced with QuestionnaireStore.additionalContext and QuestionnaireStore.setAdditionalContext respectively. You most likely won't need to call setAdditionalContext manually.

• It is still recommended to create your own wrapper function that calls destroyForm() to clean up states when the form is unmounted before calling buildForm() again.

  async function resetAndBuildForm(params: BuildFormParams) {
    // Destroy previous questionnaire state before building a new one
    destroyForm();
  
    // Build new questionnaire state
    await buildForm(params);
  }
  

RendererStylingStore changes

• RendererStylingStore and interface RendererStyling are replaced with RendererConfigStore and RendererConfig respectively. This is purely a naming change.
• rendererConfigOptions can now be passed into the renderer via buildForm() and useBuildForm(). You no longer need to call setRendererConfigStore manually.

Misc hook/function changes

• useStringCalculatedExpression and useCodingCalculatedExpression hooks are removed. CalculatedExpressions are now triggered via an internal task queue. If you are using these hooks in a component override, you can remove the hook safely.
• objectIsCoding library function is removed.

Fixed

• Take questionnaire-unit into account when updating QR via Quantity item calculatedExpressions.

[0.45.1] - 2025-02-25

Fixed

• Fixed an issue where radio buttons and checkboxes are unreadable on mobile viewports.

[0.45.0] - 2025-02-18

Added

• Added preferredTerminologyServer compatibility with valueUri.

Fixed

• Increased renderer's tolerance when working with valueCoding without codes.

[0.44.4] - 2025-02-17

Fixed

• Update dependencies to fix incompatible Node and dependency versions.

[0.44.3] - 2024-11-07

NPM-related

• Bump version to set NPM tag to latest.

[0.44.2] - 2024-10-18

Fixed

• Fixed an issue where inputs in checkbox open-choice's open label field does not update the QuestionnaireResponse.

[0.44.1] - 2024-10-14

Fixed

• Fixed unexpected behaviour of open-choice's open label field clearing the answers of previously selected options.
• Fixed an issue where enableWhen logic was not working properly with repeating items.

[0.44.0] - 2024-10-09

Added

• Added support for the preferredTerminologyServer SDC extension.

[0.43.1] - 2024-10-04

Changed

• Completely removed persisting "iframe-resizer" dependencies as a follow-up to v0.43.0.

[0.43.0] - 2024-10-04

Changed

• Removed external dependency on "iframe-resizer" while retaining dynamically sized Storybook iframes in the documentation.

[0.42.0] - 2024-09-27

Changed

• Replaced all instances of cloneDeep() with the native structuredClone() function.
• Changed Storybook iframes in the documentation to be dynamically sized based on the content.

[0.41.0] - 2024-09-25

Changed

• Significantly improved performance by reducing the number of re-renders.
• Adjusted renderer's background color to be #fafafa.
• Removed left and right paddings from the renderer - it now takes up the full width of its container.

Fixed

• Fixed inconsistencies when syncing the renderer's internal state with externally-generated QuestionnaireResponses.
• Fixed inconsistencies with internal IDs for tracking repeating items and groups.
• Fixed an issue where the renderer's theme was overriding the parent app's styles.
• Fixed issues with lodash dependencies in package.json.

Added

• Added a library function removeInternalIdsFromResponse() to remove internal IDs for tracking repeating items.

[0.40.1] - 2024-09-18

Fixed

• Fix date validation error message for two matches.
• Fix generation of internal IDs for repeat items and groups to be consistent and sync-able with externally-generated QuestionnaireResponses.
• Added a simple, minimal fix to dynamically adjust field positions based on viewport

[0.40.0] - 2024-09-06

Added

• Added support for Observation-based extraction as a library function and as a feature in the Playground.

[0.39.0] - 2024-09-06

Changed

• Refactored repeat items so that it tracks item instances using the QuestionnaireResponse, instead of using React's useState.

Fixed

• Fixed an issue where string and text items were automatically removing inputted trailing whitespaces.

[0.38.4] - 2024-08-29

Fixed

• Fixed support for item.initial and item.answerOption.initialSelected for repeating groups.

[0.38.3] - 2024-08-23

Added

• Added support for non-repeating group table (gtable) items.

[0.38.2] - 2024-08-21

Added

• Added support for Quantity items. See documentation and Storybook for more details.

[0.37.2] - 2024-08-19

Fixed

• Fixed a @aehrc/sdc-populate library dependency issue.

[0.37.1] - 2024-08-05

Added

• Added support for page UI Control code from https://hl7.org/fhir/extensions/ValueSet-questionnaire-item-control.html.

[0.36.1] - 2024-07-23

Added

• Add support for Coding type in calculatedExpressions for choice and open-choice items.

[0.36.0] - 2024-07-22

Added

• Add Save-Extract-Write functionality (StructureMap-based) in the "Save as Final" button in the Smart Forms app.