feat(#62): markdown support for labels, hints, and constraint messages #511

garethbowen · 2025-10-08T01:31:48Z

I have verified this PR works in these browsers (latest versions):

What else has been done to verify that this works as intended?

Automated tests

Why is this the best possible solution? Were any other approaches considered?

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

Markdown processing runs automatically on all labels, so forms that include markdown styling accidentally will look different, for example, questions starting with a number will now be rendered as an ordered list which means they will be indented when they weren't before.

Do we need any specific form for testing your changes? If so, please attach one.

From this branch: /packages/common/src/fixtures/notes/3-notes-with-markdown.xml

What's changed

changeset-bot · 2025-10-08T01:31:53Z

🦋 Changeset detected

Latest commit: ebb6434

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@getodk/xforms-engine	Minor
@getodk/web-forms	Minor
@getodk/scenario	Minor
@getodk/common	Minor
@getodk/xpath	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

packages/common/src/fixtures/select/1-static-selects.xml

packages/scenario/src/jr/Scenario.ts

garethbowen · 2025-10-08T01:34:45Z

packages/web-forms/src/assets/styles/reset.scss

-span,
-label {
-	font-weight: normal;
-}


I'm not sure why this was in the reset in the first place and I couldn't find anything that changed when I removed this. It's needed because if the markdown sets something as bold and then there's an inner span/p you don't expect it to be overwritten by this css again.

It’s probably meant to fix an issue when running Web Forms within Central. This reset file was mainly added to reduce overrides from Central's CSS. Hopefully, we can make Web Forms a standalone app soon and avoid these kinds of issues altogether.

Good thinking! I've had a look in central and it still seems to work. In ControlLabel.vue we have label: { font-weight: 400} which over-rights the bolding from central without the need for the reset. I wonder if the reset was added first, and then we specified the weight again at a later date making the reset unnecessary. An alternative would be for the reset to use inherit instead of normal but I unless I find something broken I'd rather remove it altogether.

I'm testing this branch in Central and the Select's options are bold now because Central's bootstrap is overriding the styles.

Before:

After:

Good find! I'm going to do more extensive testing inside Central when I deploy to the test server. In the meantime I've fixed this by using inherit which overrides the Central bootstrap but not the weight when nested inside a <strong>.

span, label { font-weight: inherit; }

packages/web-forms/src/components/form-elements/ControlLabel.vue

packages/xforms-engine/src/instance/text/TextChunk.ts

garethbowen · 2025-10-08T01:43:08Z

@latin-panda Review please! It's a fairly big change and much more complex than I'd like - feedback welcome!

garethbowen · 2025-10-08T01:43:46Z

My todo list...

make sure the styling works when used in central
go through the issue again and make sure I haven't missed anything
get this through qa

latin-panda · 2025-10-08T19:21:30Z

Great! I plan to review and test this later today and will look for additional forms to test.

latin-panda

Clear and easy to follow ✨
I’m still testing, but I’m adding some comments in the meantime.

packages/scenario/test/label-hint-text.test.ts

latin-panda · 2025-10-09T11:46:21Z

packages/web-forms/src/assets/styles/reset.scss

-span,
-label {
-	font-weight: normal;
-}


It’s probably meant to fix an issue when running Web Forms within Central. This reset file was mainly added to reduce overrides from Central's CSS. Hopefully, we can make Web Forms a standalone app soon and avoid these kinds of issues altogether.

latin-panda · 2025-10-09T11:59:25Z

packages/web-forms/tests/components/form-elements/ControlLabel.test.ts

 	},
 } as AnyInputNode;

 describe('ControlLabel', () => {


I feel this test has lost a lot of its value. It’s probably better to just have the E2E test asserting the labels and maintain only that one instead (and remove this). What do you think?

just have the E2E test asserting the labels

Does this test already exist? Or are you thinking once the select one from map work is merged I write an e2e test to take a screenshot which checks for both markdown formatting and the required styling?

There are tests already asserting that the label text is displayed, but not for "required" or other visual elements; we would need to create those tests.

packages/common/src/fixtures/select/1-static-selects.xml

packages/xforms-engine/src/client/MarkdownNode.ts

packages/xforms-engine/src/instance/text/markdownFormat.ts

latin-panda · 2025-10-09T12:50:32Z

packages/xforms-engine/src/instance/text/markdownFormat.ts

+	if (!entries.length) {
+		return;
+	}
+	return Object.fromEntries(entries) as StyleProperty;


Ah, the object could be built within the earlier loops to avoid that extra bit of processing.

That was my initial attempt but I couldn't get the TS compiler to allow it. Because StyleProperty has readonly properties I couldn't set them one at a time in the loop. The way the engine usually does it would be to hand off all the parsing to the constructor which can set the properties before init completes, but that's a bit too much OO for me. There's probably some clever pattern I'm missing that's more idiomatic - any ideas?

Yes, I can see the issue, as long as performance is good, this should be fine and still clear.

packages/xforms-engine/src/instance/text/markdownFormat.ts

packages/scenario/test/markdown.test.ts

latin-panda · 2025-10-10T19:02:49Z

I reviewed the code again, and it looks good! I also tested it with some forms but didn't do a full regression. I found a few issues:

1.. Central's bootstrap is overriding select's options

2.. The text's line breaks aren't effective anymore; this is something reported by the forum before that we fixed here

In `main` branch

In this branch

3.. Is this <qrcode> element part of this work, and what should it render? If that's for later, please create a ticket.

In `main` branch

In this branch

4.. This form displays more styles in Collect than this branch deployed in Central

styletest.xlsx

In Collect

In this branch

5.. The image isn't displayed in the label

formstyling.xlsx

Note this form combines markdown titles with emojis to increase the size of the emoji, to test this forum post: https://forum.getodk.org/t/large-single-character-emoji-text-display/56875

In Collect

In this branch

garethbowen · 2025-10-12T23:00:12Z

Central's bootstrap is overriding

Thanks. Fixed (more details in PR).

The text's line breaks aren't effective anymore; this is something reported by the forum before that we fixed

Ooh yes. So the previous fix was to use white-space: pre-wrap; which meant line breaks and spaces were respected, but with markdown formatting these are stripped out and replaced with <p> tags so the pre-wrap doesn't do anything any more. Unfortunately every bit of text was getting marked down with <p> tags (eg: option labels) which adds a whole lot of extra padding to things we don't want to be padded. To get around this I had just swallowed the p tags which is why you're seeing it all on one line. My latest version leaves the <p> tags everywhere, but changes the margin - if a p has a following sibling then the margin bottom is 1rem, if not, it's 0. This overrides the Central styling and looks identical in everything I've tested but may have regressed somewhere else.

Also I've edited the "all question types" xml so the "version" information is in an html list rather than attempting to manually indent it.

Is this element part of this work, and what should it render?

It's not part of this work, and I'm not sure what it should render. The current rendering is consistent with Enketo. Issue raised: #520

This form displays more styles in Collect than this branch deployed in Central

I had configured the DOMPurify to be highly restrictive, and only allow for elements which weren't already covered by markdown, ie: for a heading use # not <h1>. I see now that we should allow both so I've switched DOMPurify back to the default which is much more permissive but still safe against injection. Now this branch renders all of those (and even gets the nested list elements correct which Collect isn't!).

The image isn't displayed in the label

This is also a problem in main. I've fixed this by including the code from the TextMedia template in the ControlLabel template.

Note this form combines markdown titles with emojis to increase the size of the emoji

This is working in this branch, but because it's a h5 the emoji also has top and bottom margin. I think this is acceptable for now, but would be worth looking at a better solution for this which didn't involve headings. I've added support for the font-size style property to be passed through which will get some way towards a solution for this.

packages/common/src/fixtures/preview-service/xforms/all-question-types-v2024091201-3.xml

latin-panda · 2025-10-13T17:40:17Z

Is this element part of this work, and what should it render? If that's for later, please create a ticket.

It's not part of this work, and I'm not sure what it should render. The current rendering is consistent with Enketo. Issue raised: #520

Interesting! The print appearance for text inputs displays the value as a read-only note. I guess if someone uses markdown, it should style it accordingly.

When you click the print button, it generates a QR code.

latin-panda

Nice! I added a few questions and some observations from my tests in the Safari browser.
Have you tested on Android or iPhone? I reached my free quota of requests and couldn't test it. I need to find another backup service.

You'll need to add the tunnel address in package/web-forms/vite.config.ts:

latin-panda · 2025-10-14T12:15:50Z

packages/web-forms/src/components/form-elements/ControlHint.vue

 <template>
 	<div v-if="question.currentState.hint" class="hint">
-		{{ question.currentState.hint?.asString }}
+		<MarkdownBlock v-for="(elem, index) in question.currentState.hint?.formatted" :key="index" :elem="elem" />


Web Forms stand-alone is good. But I noticed that Central is making the text cut in a weird place. Can you add something here, use all the space available? Or in the reset file

I propose we leave this as is - the Central team have decided that anything wider than 77ch is not readable. In this case it doesn't actually break web-forms and if they want to change it it can be reset on their side. If we start including overrides for everything any customer may have set in the parent context we'll end up with the world's biggest reset file (eg: we'd also have to do something about the following line p:lang(ja), p:lang(zh) { max-width: 54ch; }). What do you think?

Okay, in WF standalone, the text is fully expanded. This only affects WF in Central.

We might get some issues reported, in that case, we'll coordinate with Central team to fix those css conflicts.

latin-panda · 2025-10-14T12:34:15Z

packages/web-forms/src/assets/styles/reset.scss

 span,
 label {
-	font-weight: normal;
+	font-weight: inherit;


I still see the issue in Central, Safari browser. The font-weight with 400 works in p element (L51). The inherit value didn't work.

Yes 😭

So the reset wasn't really working - even for the question labels we had specific weight override in ControlLabel.vue. I've added the same in select-options.scss.

latin-panda · 2025-10-14T12:44:02Z

packages/web-forms/src/assets/styles/reset.scss


+label,
+.hint {
+	p {


The p with text is there but has no color

Oof. I'm not sure why this changed - I would expect it to be broken in main too. Bottom line is Central defines a .label { color: white } and we don't override it either in main or this branch. Fixed by overriding.

Hmm, I wonder if it's some new code on their affecting Web Forms.

latin-panda · 2025-10-14T12:50:46Z

packages/xforms-engine/src/client/MarkdownNode.ts

+export interface StyleProperty {
+	readonly color: string | undefined;
+	readonly 'font-family': string | undefined;
+	readonly 'text-align': 'center' | 'left' | 'right' | undefined;


In Collect, each option is centered aligned when using text-align.

In Central + this branch:

This is the styletest form I shared the other day.

This is caused by the max-width: 77ch as above. The reason it doesn't line up with the label is the font-size in the label is bigger and therefore the max-width is wider. As above, I propose leaving this for Central to define whatever max-width they want.

FYI @srujner

latin-panda · 2025-10-14T12:54:10Z

packages/web-forms/src/components/common/MarkdownBlock.vue

+	<span v-else-if="elem.role === 'html'" v-html="purify(elem)" />
+
+	<!-- link -->
+	<a v-else-if="elem.role === 'parent' && elem.elementName === 'a'" :href="getUrl(elem)" target="_blank">


This link is opening in the same tab. I guess this elem.role is HTML instead of a (so rendering L44)

Yes precisely. I wanted to avoid actually parsing the HTML and just sanitizing it which means we're limited about what changes we can make to it. In this case, the person building the form would have to specify the target attribute. Is that ok?

Okay 👍 that's reasonable

latin-panda · 2025-10-14T12:58:35Z

packages/web-forms/src/components/form-elements/ControlLabel.vue

-		<span>{{ props.question.currentState.label?.asString }}</span>
+	<label :for="question.nodeId" :class="{ required: question.currentState.required }">
+		<MarkdownBlock v-for="(elem, index) in text" :key="index" :elem="elem" />
+		<div v-if="image || video || audio" class="media-content">


I think this Label's image should be left-aligned - @alyblenkin is that correct?

It'd be good to test loading a small image and a big image. I wonder if we need to add max-width

For example, the image question type has a box for small images, and has a max-width for big images.

This could be getting out of scope, and we can address it in another ticket.

I'd like to put this out of scope, because it may require design input separate testing, etc. Should I remove the image handling code that I added pending dev on the separate issue, or do you think I leave it in there because it's better than nothing?

I think it's better to leave this code as is, showing an image is preferable to showing nothing. Can you please create a ticket to style it and tag Aly for input? :)

Issue raised: #525

garethbowen · 2025-10-15T00:17:58Z

Have you tested on Android or iPhone?

I've tested Android. Unfortunately I don't have access to an iPhone.

latin-panda

Exciting to have this ready. Thanks! 🤩

garethbowen · 2025-10-16T02:17:22Z

@latin-panda Sorry to bother you again, but Szymon sent through the first of the QA forms and I found another issue, which led me down a rabbit hole of more markdown in more places! Would you mind reviewing the last 3 commits as well?

latin-panda

Do we need to support this in a map's properties pop-up? I don't think so, but I'm asking to double-check.

I left some other comments below

latin-panda · 2025-10-16T08:54:15Z

packages/web-forms/src/components/common/MultiselectDropdown.vue

 	panelClass += ' no-buttons';
 }
+
+const getSelectedLabels = () => {


This could be a Vue's computed.
Ref: https://vuejs.org/guide/essentials/computed#computed-caching-vs-methods

Fixed. Thanks. I need to read up more about vue...

latin-panda · 2025-10-16T08:56:39Z

packages/web-forms/src/components/common/SearchableDropdown.vue

 	});
 });

+const getSelectedLabel = () => {


Same feedback here

latin-panda · 2025-10-16T09:08:41Z

packages/web-forms/src/components/common/SearchableDropdown.vue

 		@change="$emit('change')"
-	/>
+	>
+		<template #option="slotProps">


The search is no longer working. It is case-insensitive, matches based on the label, and finds matches anywhere within the text.

Before:

In this branch:

Thanks for finding this. It turns out it needs a string to work. I've fixed this by passing the asString value in as the option-label.

latin-panda · 2025-10-16T09:14:58Z

packages/web-forms/src/components/common/SearchableDropdown.vue

+			<MarkdownBlock v-for="(elem, index) in slotProps.option.label.formatted" :key="index" :elem="elem" />
+		</template>
+		<template #value>
+			<MarkdownBlock v-for="(elem, index) in getSelectedLabel()" :key="index" :elem="elem" />


It's not showing the comma between elements, so now it's difficult to read the selection.

Before:

In this branch:

Ooh, yeah. I've updated the #value template so it adds the comma in between. With options that don't use markdown it looks identical to before. With markdown it's got a bit more padding just because of the whitespace between HTML tags. I think it's ok, and difficult to manage without knowing what HTML they've included...

srujner · 2025-10-16T11:58:05Z

Which one is the correct behavior?

WebForms

Enketo

latin-panda · 2025-10-16T13:42:58Z

@srujner Collect displays selections as a comma-separated list, which better conveys what was selected rather than how many items were chosen.

garethbowen · 2025-10-16T19:21:54Z

Do we need to support this in a map's properties pop-up?

I think not. Let's leave it for now and revisit it once we have a use case. Because you can include structured elements it could break out of the list structure really easily...

garethbowen commented Oct 8, 2025

View reviewed changes

packages/common/src/fixtures/select/1-static-selects.xml Outdated Show resolved Hide resolved

garethbowen commented Oct 8, 2025

View reviewed changes

packages/scenario/src/jr/Scenario.ts Show resolved Hide resolved

garethbowen commented Oct 8, 2025

View reviewed changes

packages/web-forms/src/components/form-elements/ControlLabel.vue Show resolved Hide resolved

garethbowen commented Oct 8, 2025

View reviewed changes

packages/xforms-engine/src/instance/text/TextChunk.ts Show resolved Hide resolved

garethbowen requested a review from latin-panda October 8, 2025 01:42

garethbowen linked an issue Oct 8, 2025 that may be closed by this pull request

Design: Markdown in label/hint (and TextRange engine/client API generally) #198

Open

latin-panda reviewed Oct 9, 2025

View reviewed changes

packages/scenario/test/markdown.test.ts Show resolved Hide resolved

latin-panda reviewed Oct 13, 2025

View reviewed changes

packages/common/src/fixtures/preview-service/xforms/all-question-types-v2024091201-3.xml Show resolved Hide resolved

latin-panda mentioned this pull request Oct 13, 2025

Support printer widget #520

Open

8 tasks

garethbowen added 12 commits October 14, 2025 10:17

poc

9f697f6

day 2 poc

7ccc1a6

most of markdown is working

4892b83

add more test types

2003aed

more markup handled

2c0512a

format hints too

435be16

much cleanup, and supporting more cases

0379758

revert temporary package hack

5d2ae7f

fix test

92e5533

fix test

07639b1

fix e2e test - labels no longer have spans inside

a1108b9

label must be a block elem now, bring * inline with first elem

ddcbb48

garethbowen added 11 commits October 14, 2025 10:18

fix test

bd5175a

add test for jr:choice-name

1e56c7e

fixed a bug with single quoted styles, and cleanup

b0d3c00

add changeset

748d0f4

update the feature matrix

511193b

review feedback

4ebe5f1

fix test name

15e5a46

review feedback

7c80160

modify test to allow labels to have inner elements

37fe793

add non breaking spaces to test indentation

8380785

update xlsx with list format instead of indentation

25901c5

garethbowen force-pushed the 62-markdown branch from 35f83a5 to 25901c5 Compare October 13, 2025 21:20

fix label selector

a3a27af

garethbowen requested a review from latin-panda October 13, 2025 22:10

latin-panda requested changes Oct 14, 2025

View reviewed changes

provide specific overrides for some central styles

1a1c11c

latin-panda self-requested a review October 15, 2025 03:52

latin-panda approved these changes Oct 15, 2025

View reviewed changes

garethbowen added the needs testing label Oct 15, 2025

garethbowen added 3 commits October 16, 2025 12:52

use markdown for groups, repeats, and select options

c114e34

fix tests

c9e9995

markdown validation messages

21d2df0

garethbowen mentioned this pull request Oct 16, 2025

Support images in labels #525

Open

8 tasks

latin-panda requested changes Oct 16, 2025

View reviewed changes

review feedback

ebb6434

feat(#62): markdown support for labels, hints, and constraint messages #511

Are you sure you want to change the base?

feat(#62): markdown support for labels, hints, and constraint messages #511

Uh oh!

Conversation

garethbowen commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I have verified this PR works in these browsers (latest versions):

What else has been done to verify that this works as intended?

Why is this the best possible solution? Were any other approaches considered?

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

Do we need any specific form for testing your changes? If so, please attach one.

What's changed

Uh oh!

changeset-bot bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

latin-panda Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

garethbowen commented Oct 8, 2025

Uh oh!

garethbowen commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

latin-panda commented Oct 8, 2025

Uh oh!

latin-panda left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

latin-panda commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

garethbowen commented Oct 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

latin-panda commented Oct 13, 2025

Uh oh!

latin-panda left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

garethbowen commented Oct 8, 2025 •

edited

Loading

changeset-bot bot commented Oct 8, 2025 •

edited

Loading

latin-panda Oct 10, 2025 •

edited

Loading

garethbowen commented Oct 8, 2025 •

edited

Loading

latin-panda commented Oct 10, 2025 •

edited

Loading

garethbowen commented Oct 12, 2025 •

edited

Loading