Events to hook this up to our Angular reactive forms

[dietergeerts]

Hi, we are trying to use the web component inside our Angular app, but I can't seem to find a correct way of hooking the component up with our reactive form, so that we can set touched and propagate changes. Are there events available currently that I've missed, or is there other ways to watch for changes on the web component? I didn't yet look at trying to use the Angular component directly because I want to avoid Angular version clashes, but we also want to use the web component within React apps later on. The regular change event could be used, but I'm not sure it it will always work, as that will depend on the actual controls within, and we don't have control over this. Thx in advance.

[lhcye]

What kind of the events do you need? LHC-Forms web component emits only two events when a Questionnaire is loaded, onFormReady and onError. See details here, https://github.com/LHNCBC/lforms/blob/master/form_definition.md#emitted-events

It does not emit events like data changes or keyboard/mouse events. The common use case of LHC-Forms is to use it render a Questionnaire with all the supported features and get a QuestionnaireResponse out of it. The npm package does not include a Angular component version of LHC-Forms, so that more events/hooks from internal components could be available. It should be possible to create one but we have not tried that approach.

LHC-Forms web component has been used on Angular apps and React apps.

[dietergeerts]

What kind of the events do you need?

We want to hook it up to our reactive forms, so whenever a change on the data is happening, and whenever there is a "touch" of the controls. We're wrapping the web component within a custom control (CVA), because it's part of a larger form, and we want to have it behave similar for error display etc... So it would be great if those events are exposed.

[lhcye]

We could probably emit an onChange event with linkId, new data etc. I am not sure the event on UI, such as the keyboard, mouse and touch events, should be emitted from the LHC-Forms widget. Let me know if having an onChange event will work in your case.

[dietergeerts]

We could probably emit an onChange event with linkId, new data etc. I am not sure the event on UI, such as the keyboard, mouse and touch events, should be emitted from the LHC-Forms widget. Let me know if having an onChange event will work in your case.

It will depend if we can fully incorporate it into a full form. For now, I have made a custom Angular control wrapping the LForms web component. I use the HTML change event that bubbles from the inner controls to know there is a change, and use the LForms API to then extract the data. I use the focusout en focusin events to trigger the Angular touched state. Within our form, we add extra fields like a notes field and some checkboxes. Any event that would enable us to easily hook up to Angular custom control would be awesome, because with the HTML change event, we'll probably not cover all possible inner controls.

[dietergeerts]

Something to note here though is that the change event is too early because the data is not yet updated at that time. So the above code doesn't fully work as the last change will not be returned yet. Therefore an explicit event from the LForms web component would be great, or something we can subscribe to on the global API, or a callback we can pass in.

[lhcye]

You said "Within our form, we add extra fields like a notes field and some checkboxes.". I wonder if you are adding extra fields because LHC-Forms has not supported those fields/extensions yet. If that's the case we can add those support. That might be an easy approach for us and probably for you too.

[plynchnlm]

@dietergeerts Reading your message, my understanding is that you would like LForms to emit a change event that indicates the form data model has changed. Is that correct? If so, do you need to know which values have changed? You could just get the current QuestionnaireResponse structure via LForms.Util.getFormFHIRData('QuestionnaireResponse', 'R4'). Trying send just a delta of that could be tricky (especially for removed data).

[dietergeerts]

@dietergeerts Reading your message, my understanding is that you would like LForms to emit a change event that indicates the form data model has changed. Is that correct? If so, do you need to know which values have changed? You could just get the current QuestionnaireResponse structure via LForms.Util.getFormFHIRData('QuestionnaireResponse', 'R4'). Trying send just a delta of that could be tricky (especially for removed data).

I currently use the HTML change event (that's triggered from native inputs etc...), but if that works will depend on the actual controls. So having an explicit "data change" event from the LForms form would be great, as then we can be certain it has changed, because right now, I also have to add a timeout, because the change event happens, and LForms is still to update the code. Getting the data as a whole from that interface is ok, as we do wrap it in a custom control. The following is our current implementation of the control wrapping LForms. Having the explicit "data changed" event will help to get rid of the timeouts and ensure it's always triggered when there are changes.

import { ChangeDetectionStrategy, Component, ElementRef, inject, input, signal } from "@angular/core";
import { takeUntilDestroyed, toObservable } from "@angular/core/rxjs-interop";
import type { Questionnaire, QuestionnaireResponse } from "fhir/r4";
import { combineLatest, concatMap, debounceTime, defer, Subject } from "rxjs";

import { FormControlComponent, formControlProvider } from "@intocare/angular-forms/lib/form-control.component";
import { TouchedOnFocusLostDirective } from "@intocare/angular-forms/lib/touched-on-focus-lost.directive";

/**
 * The LForms web component will add a global constant to expose its API and scope its own code.
 * The package currently doesn't contain types, but we can look at their docs and inspect their
 * source code to construct some types to help us out here, as this is the wrapper for it.
 * (!) These types aren't complete, they are implemented on an as-needed basis!
 * @see https://lhncbc.github.io/lforms
 */
declare const LForms: {
	Util: {
		addFormToPage(
			formDefinition: Questionnaire,
			formContainer: HTMLElement,
			options: {
				fhirVersion: "R4";
				questionnaireResponse: QuestionnaireResponse | undefined;
			},
		): Promise<void>;
		removeFormsFromPage(formContainer: HTMLElement): void;
		getFormFHIRData(
			resourceType: "QuestionnaireResponse",
			fhirVersion: "R4",
			formDataSource: HTMLElement,
		): QuestionnaireResponse;
	};
};

/**
 * Form control to wrap the LForms web component and hook it up with our forms.
 *
 * The required LForms global scripts are included in the build via project.json.
 * @todo Wait for a future version to import the scripts here instead, or find an alternative inclusion mechanism,
 * 		as this will then enable us to write stories and unit tests (specs) for this component.
 *
 * LForms web component doesn't expose events for interactions, so we'll use the internal HTML events instead.
 * @see https://github.com/LHNCBC/lforms/issues/189
 */
@Component({
	selector: "ic-assessment-form-control",
	changeDetection: ChangeDetectionStrategy.OnPush,
	providers: [formControlProvider(() => AssessmentFormControlComponent)],
	template: "", // The content will be replaced by the LForms web component.
	styleUrl: "./assessment-form-control.component.scss",
	hostDirectives: [TouchedOnFocusLostDirective],
	host: { "(change)": "internalChangeEvent$.next($event)" },
})
export class AssessmentFormControlComponent extends FormControlComponent<QuestionnaireResponse | null> {
	private readonly nativeElement = inject<ElementRef<HTMLElement>>(ElementRef).nativeElement;
	private readonly writeValue$ = new Subject<QuestionnaireResponse | null>();
	protected readonly internalChangeEvent$ = new Subject<Event>();

	readonly dataQuestionnaire = input.required<Questionnaire>();

	protected override readonly value = signal<QuestionnaireResponse | null>(null);

	/**
	 * Updates the form control value after LForms has consumed the internal change event itself.
	 *
	 * As there are currently no explicit events from the LForms web component we can hook into, we use raw HTML events
	 * from its internal controls instead to know if there are data changes. However, at the time of the event, the web
	 * component itself still needs to update its internal data before we can request it and update our control value.
	 */
	private readonly updateValueAfterLFormsChanges = this.internalChangeEvent$
		.pipe(
			/**
			 * Give LForms web component time to update its internal data first before we ask for it.
			 *
			 * Instead of just a delay, we use debounce to also minimize calling the LForms API to collect the data.
			 * So this is used for giving LForms time to update, but also to batch quick changes done by the user.
			 * The exact time of `360` seems to work, though in the future, we should use explicit events instead,
			 * something we're discussing on the LForms repo: https://github.com/LHNCBC/lforms/issues/189
			 */
			debounceTime(360),
			takeUntilDestroyed(),
		)
		.subscribe(() => {
			this.value.set(LForms.Util.getFormFHIRData("QuestionnaireResponse", "R4", this.nativeElement));
			this.onChange();
		});

	/**
	 * @internal
	 */
	override writeValue(value: QuestionnaireResponse | null): void {
		this.value.set(value);
		this.writeValue$.next(value);
	}

	/**
	 * Initialize the LForms web component whenever the questionnaire or response changes from the outside.
	 *
	 * To ensure we don't render the form twice on initialization, we need to ensure we have the questionnaire, and that
	 * Angular has pushed the initial form value (questionnaire response). From then on, we need to re-render the LForm
	 * whenever the questionnaire or -response changes from the outside, as the LForm web component currently doesn't
	 * expose an API to update the existing form nor its current value (response).
	 */
	private readonly initializeFormOnContextChange = combineLatest({
		questionnaire: toObservable(this.dataQuestionnaire),
		questionnaireResponse: this.writeValue$,
	})
		.pipe(
			takeUntilDestroyed(),
			concatMap(({ questionnaire, questionnaireResponse }) =>
				defer(() => {
					LForms.Util.removeFormsFromPage(this.nativeElement);
					return LForms.Util.addFormToPage(questionnaire, this.nativeElement, {
						fhirVersion: "R4",
						questionnaireResponse: questionnaireResponse ?? undefined,
					});
				}),
			),
		)
		.subscribe({
			complete: () => {
				LForms.Util.removeFormsFromPage(this.nativeElement);
			},
		});
}

[lhcye]

We can add something like an "onChange" event that emits an array of info (linkId, current value, previous value, etc.) about the items that have changed data, which is triggered by changes that will result in a different QuestionnaireResponse. Let me know if that works.

[dietergeerts]

We can add something like an "onChange" event that emits an array of info (linkId, current value, previous value, etc.) about the items that have changed data, which is triggered by changes that will result in a different QuestionnaireResponse. Let me know if that works.

Yes, that will work for us, thx.

[kenzoheye]

I would love for this implementation to be prioritized!

[MouradEssebaneCorilus]

I would like this as well.

[lhcye]

It's in progress.

[jcy1225]

Hi @dietergeerts , a few questions for the new 'onChange' event:

1. Do you want the event emitted when a repeating row is add or removed? Adding a repeating row without filling out the new row does not change the QuestionnaireResponse, but removing a repeating row does. Your current implementation based on HTML 'change' event may not catch removing of input elements.
2. A data change on one item may result in some other items anywhere in the form to be shown or hidden through skip logic, changing the QuestionnaireResponse on multiple nodes. I believe you would want the event to be emitted with all the changes, not just the original item change?
3. Addressing the above scenario, it would be a cleaner solution to have the event emit without any details, instead of trying to track every changes caused by skip logic and return an array of {linkId, current value, previous value}. The event would only tell you that something changed, and you would get the updated QuestionnaireResponse through API just like you do now. Does this solution sound plausible?

[kenzoheye]

Hey @jcy1225

I will take the liberty of answering here since Dieter and I are colleagues and working on the same problem. I do not speak for him but this is my take:

1. Repeating adds/removes: Yes please emit! Even if the FHIR output is not changing the shape of the form can change. Our wrapper should re-sync to reflect that (validation, dirty states, ...). Removing a row is an obvious data change. Both are currently invisible to a plain HTML (change) listener.

2. Skip-logic / update cascades: It would be nice if 1 "update chain" could be debounced, since LForms knows when the internal recomputation is finished. Emitting one event per user-trigger / change is exactly what we need. It avoids us debouncing and adding timers.

3. No-detail events would be preferable: This is the cleanest for us since our current implementation already pulls the full QuestionnaireResponse and sets it in a signal / formControl like this.value.set(LForms.Util.getFormFHIRData("QuestionnaireResponse", "R4", this.nativeElement));. Any per-item event data like a delta we would never use. I think a type of event and some metadata about what triggered the event could always be useful for debugging and filtering purposes.

A single notification, for example a CustomEvent like lhcFormDataChange dispatched on the wh-lhc-form host allows us to reduce our implementation to:

  fromEvent(lhcFormElement, 'lhcFormDataChange')
    .pipe(takeUntilDestroyed())
    .subscribe(() => this.value.set(
      LForms.Util.getFormFHIRData('QuestionnaireResponse', 'R4', lhcFormElement),
    ));