(feat) Add form engine cookbook reference form

[denniskigen]

Summary

Add a Form Engine Cookbook reference form to the demo content package. The form is a working library of patterns supported by the OpenMRS 3 form engine, intended for form authors (implementers, country teams, anyone editing form JSON, in or out of Form Builder).

Each page covers one authoring task with the same shape:

1. Scenario — what a form author is trying to achieve, in plain language ("you want a field to appear only when another answer is set").
2. Shape — the JSON snippet to copy.
3. Notes — gotchas, alternatives, when not to use it.

Topics covered, page by page:

• Conditional visibility — hide.hideWhenExpression, disabled.disableWhenExpression, static isDisabled
• Required variants — boolean, expression-based, conditionalAnswered
• Validators — js_expression, date, conditionalAnswered, default_value
• Computed fields — calculate.calculateExpression and the helper library (calcBMI, calcEDD, z-score family, etc.)
• Previous-value and historical — formOptions.usePreviousValueDisabled, enablePreviousValue, historicalExpression with the HD helper
• Special renderings — toggle, content-switcher, fixed-value, select-concept-answers, extension-widget
• Special field types — patientIdentifier, personAttribute, testOrder, programState
• Form-level metadata — availableIntents, behaviours overrides, postSubmissionActions, embedded translations, meta.programs, defaultPage, allowUnspecifiedAll
• Composition — section reference and page isSubform
• Question-option grab bag — weeksList (reserved), shownDateOptions, showComment, plus other less-common keys

Most fields use real concepts from the reference-app demo metadata so the form renders end-to-end against a dev distro. Patterns that depend on chart-side context the form-builder preview can't supply (referenced sibling forms, subforms, program states) are documented via markdown explainers rather than embedded as live fields, with a note about why.

The form is published: false by design — it will not appear in the patient chart unless that flag is flipped for local testing.

Companion change

Richer markdown rendering (inline code, fenced code blocks, lists, links, blockquotes) is gated by openmrs/openmrs-esm-form-engine-lib#733, which expands the markdown wrapper's allowlist and adds the styles to match. Without that PR the cookbook still renders but loses list bullets and code-block styling — the explainer text remains readable.

[VeronicaMuthee]

@denniskigen, this is such a useful guide. Do we have such expressions?

1. To enforce a Unique Identifier
2. Pre-populating form field based on the patient's last encounter, so the clinician only has to update it if it has changed, for example, the date of the last cervical cancer screening or TPT, where previously captured
3. How about calculating the date of the next appointment, say, based on the quantity of drugs dispensed (in days)

[denniskigen]

Thanks @VeronicaMuthee, those are good suggestions.

On the unique identifier one, the engine doesn't have anything for this. Expressions can see what's on the form plus a bit of patient context (sex, age, current visit, most recent encounter via HD), but they can't reach across to other patients to check whether an identifier is already taken. That check has to come from the backend, via the identifier source and OpenMRS's identifier validator. I'll call this out on the patientIdentifier page so it doesn't send anyone hunting for a form-side option.

For pre-filling from the last encounter, this is what "Previous-value and historical" is for, but I think I framed it too abstractly to connect. The shape is historicalExpression with HD.getObject('prevEnc').getValue('<concept-uuid>'). Clinician sees the prior value and can change it if it's stale. Your "last cervical cancer screening date" / TPT framing is a much better introduction than what I had, so I'll swap one of those in.

The next-appointment-from-days-dispensed one is a natural fit for a computed field:

"calculate": { "calculateExpression": "addDaysToDate(today(), drugDurationDays)" }

where drugDurationDays is the id of the number field holding the dispensed quantity. Computed fields only has BMI and EDD right now, neither of which exercises date math, so this slots in nicely.