feat(davinci-client): support rich text and appearance in single checkbox

Author: ancheetah

.changeset/single-checkbox.md

@@ -2,10 +2,12 @@
 '@forgerock/davinci-client': minor
 ---
 
-Adds support for the SINGLE_CHECKBOX field. A new ValidatedBooleanCollector type was introduced including validation support for required checkboxes and updater support for booleans.
+Adds support for the SINGLE_CHECKBOX field. A new ValidatedBooleanCollector interface was introduced including validation support for required checkboxes and updater support for booleans.
 
 **Type improvements**
 
 - `SingleValueCollectorWithValue<T, V>` and `ValidatedSingleValueCollectorWithValue<T, V>` are now generic over their value type (`V`, defaults to `string`), replacing the loose `string | number | boolean` union
 
+- `ValidatedBooleanCollector` interface extends `ValidatedSingleValueCollectorWithValue`, intersecting `output` with `appearance: string` and `richContent?: CollectorRichContent`
+
 - `Validator` is now generic over collector type `T`, replacing the hardcoded `string` input with `CollectorValueType<T>` — so validators receive the value type that matches their collector (e.g. `boolean` for `ValidatedBooleanCollector`, `string` for text collectors) rather than always `string`

e2e/davinci-app/components/boolean.ts

@@ -9,7 +9,7 @@ import type {
   Updater,
   Validator,
 } from '@forgerock/davinci-client/types';
-import { dotToCamelCase } from '../helper.js';
+import { dotToCamelCase, richContentInterpolation } from '../helper.js';
 
 /**
  * Creates a single checkbox and attaches it to the form
@@ -36,34 +36,43 @@ export default function booleanComponent(
   const checkbox = document.createElement('input');
   checkbox.type = 'checkbox';
   checkbox.id = collectorKey;
-  checkbox.name = collectorKey || 'single-checkbox-field';
+  checkbox.name = collectorKey;
   checkbox.checked = collector.output.value;
   checkbox.value = 'checked';
 
   const label = document.createElement('label');
   label.htmlFor = checkbox.id;
-  label.textContent = collector.output.label;
+
+  const { richContent } = collector.output;
+  if (!richContent || richContent.replacements.length === 0) {
+    label.textContent = collector.output.label;
+  } else {
+    const pRichText = richContentInterpolation(richContent);
+    while (pRichText.firstChild) {
+      label.appendChild(pRichText.firstChild);
+    }
+  }
 
   // Add event listener to handle single-select behavior
   checkbox.addEventListener('change', (event) => {
     const checked = (event.target as HTMLInputElement).checked;
     const result = validator(checked);
     const errorEl = formEl?.querySelector(`.${collectorKey}-error`);
 
-    // Keep collector state aligned with the current UI value
-    const updateError = updater(checked);
-    if (updateError && 'error' in updateError) {
-      console.error(updateError.error.message);
-    }
-
     // Validate the input
     if (Array.isArray(result) && result.length && !errorEl) {
-      const errorEl = document.createElement('div');
-      errorEl.className = `${collectorKey}-error`;
-      errorEl.innerText = result.join(', ');
-      formEl?.querySelector(`#${collectorKey}`)?.after(errorEl);
+      const newErrorEl = document.createElement('div');
+      newErrorEl.className = `${collectorKey}-error`;
+      newErrorEl.innerText = result.join(', ');
+      formEl?.querySelector(`#${collectorKey}`)?.after(newErrorEl);
+    } else if (Array.isArray(result) && result.length) {
+      return;
     } else {
       formEl.querySelector(`.${collectorKey}-error`)?.remove();
+      const updateError = updater(checked);
+      if (updateError && 'error' in updateError) {
+        console.error(updateError.error.message);
+      }
     }
   });
 

e2e/davinci-app/components/label.ts

@@ -5,6 +5,7 @@
  * of the MIT license. See the LICENSE file for details.
  */
 import type { ReadOnlyCollector, RichTextCollector } from '@forgerock/davinci-client/types';
+import { richContentInterpolation } from '../helper.js';
 
 export default function (
   formEl: HTMLFormElement,
@@ -28,32 +29,7 @@ export default function (
   }
 
   // Interpolate the template by splitting on {{key}} and inserting links
-  const segments = richContent.content.split(/\{\{(\w+)\}\}/);
-  const replacementMap = new Map(richContent.replacements.map((r) => [r.key, r]));
+  const pRichText = richContentInterpolation(richContent);
 
-  for (let i = 0; i < segments.length; i++) {
-    if (i % 2 === 0) {
-      // Text segment
-      if (segments[i]) {
-        p.appendChild(document.createTextNode(segments[i]));
-      }
-    } else {
-      // Replacement key
-      const replacement = replacementMap.get(segments[i]);
-      if (replacement?.type === 'link') {
-        const a = document.createElement('a');
-        a.href = replacement.href;
-        a.textContent = replacement.value;
-        if (replacement.target) {
-          a.target = replacement.target;
-          if (replacement.target === '_blank') {
-            a.rel = 'noopener noreferrer';
-          }
-        }
-        p.appendChild(a);
-      }
-    }
-  }
-
-  formEl?.appendChild(p);
+  formEl?.appendChild(pRichText);
 }

e2e/davinci-app/helper.ts

@@ -1,3 +1,5 @@
+import { CollectorRichContent } from '@forgerock/davinci-client';
+
 /*
  * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
  *
@@ -12,3 +14,38 @@ export function dotToCamelCase(str: string) {
     )
     .join('');
 }
+
+// Interpolate the template by splitting on {{key}} and inserting links
+export function richContentInterpolation(richContent: CollectorRichContent): HTMLParagraphElement {
+  const p = document.createElement('p');
+  p.style.whiteSpace = 'pre-line';
+
+  const segments = richContent.content.split(/\{\{(\w+)\}\}/);
+  const replacementMap = new Map(richContent.replacements.map((r) => [r.key, r]));
+
+  for (let i = 0; i < segments.length; i++) {
+    if (i % 2 === 0) {
+      // Text segment
+      if (segments[i]) {
+        p.appendChild(document.createTextNode(segments[i]));
+      }
+    } else {
+      // Replacement key
+      const replacement = replacementMap.get(segments[i]);
+      if (replacement?.type === 'link') {
+        const a = document.createElement('a');
+        a.href = replacement.href;
+        a.textContent = replacement.value;
+        if (replacement.target) {
+          a.target = replacement.target;
+          if (replacement.target === '_blank') {
+            a.rel = 'noopener noreferrer';
+          }
+        }
+        p.appendChild(a);
+      }
+    }
+  }
+
+  return p;
+}

e2e/davinci-suites/src/form-fields.test.ts

@@ -51,9 +51,16 @@ test('Should render form fields', async ({ page }) => {
 
   // Single checkbox default value
   await expect(page.locator('#single-checkbox-field')).not.toBeChecked();
+
+  // Single checkbox rich text
   await expect(page.getByText('I agree to the Terms and Conditions')).toBeVisible();
+  await expect(page.getByRole('link', { name: 'Terms and Conditions' })).toBeVisible();
+  await expect(page.getByRole('link', { name: 'Terms and Conditions' })).toHaveAttribute(
+    'href',
+    'https://www.pingidentity.com',
+  );
 
-  // Toggle the single checkbox and assert that it is optional by the abscence of an error message
+  // Toggle the single checkbox and assert that it is optional by the absence of an error message
   await page.locator('#single-checkbox-field').check();
   await expect(page.locator('#single-checkbox-field')).toBeChecked();
   await page.locator('#single-checkbox-field').uncheck();
@@ -90,7 +97,8 @@ test('Should render form fields', async ({ page }) => {
 });
 
 test('should render form validation fields', async ({ page }) => {
-  await page.goto('http://localhost:5829/?clientId=e4ef2896-8d90-4abd-bf0f-7b8034995927');
+  const { navigate } = asyncEvents(page);
+  await navigate('/?clientId=e4ef2896-8d90-4abd-bf0f-7b8034995927');
 
   await expect(page.getByText('Select Form Fields Test Form')).toBeVisible();
 

packages/davinci-client/api-report/davinci-client.api.md

@@ -382,14 +382,14 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         } & Omit<{
             requestId: string;
             data?: unknown;
-            error?: FetchBaseQueryError | SerializedError | undefined;
+            error?: SerializedError | FetchBaseQueryError | undefined;
             endpointName: string;
             startedTimeStamp: number;
             fulfilledTimeStamp?: number;
         }, "data" | "fulfilledTimeStamp"> & Required<Pick<{
             requestId: string;
             data?: unknown;
-            error?: FetchBaseQueryError | SerializedError | undefined;
+            error?: SerializedError | FetchBaseQueryError | undefined;
             endpointName: string;
             startedTimeStamp: number;
             fulfilledTimeStamp?: number;
@@ -406,7 +406,7 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         } & {
             requestId: string;
             data?: unknown;
-            error?: FetchBaseQueryError | SerializedError | undefined;
+            error?: SerializedError | FetchBaseQueryError | undefined;
             endpointName: string;
             startedTimeStamp: number;
             fulfilledTimeStamp?: number;
@@ -423,14 +423,14 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         } & Omit<{
             requestId: string;
             data?: unknown;
-            error?: FetchBaseQueryError | SerializedError | undefined;
+            error?: SerializedError | FetchBaseQueryError | undefined;
             endpointName: string;
             startedTimeStamp: number;
             fulfilledTimeStamp?: number;
         }, "error"> & Required<Pick<{
             requestId: string;
             data?: unknown;
-            error?: FetchBaseQueryError | SerializedError | undefined;
+            error?: SerializedError | FetchBaseQueryError | undefined;
             endpointName: string;
             startedTimeStamp: number;
             fulfilledTimeStamp?: number;
@@ -477,14 +477,14 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         } & Omit<{
             requestId: string;
             data?: unknown;
-            error?: FetchBaseQueryError | SerializedError | undefined;
+            error?: SerializedError | FetchBaseQueryError | undefined;
             endpointName: string;
             startedTimeStamp: number;
             fulfilledTimeStamp?: number;
         }, "data" | "fulfilledTimeStamp"> & Required<Pick<{
             requestId: string;
             data?: unknown;
-            error?: FetchBaseQueryError | SerializedError | undefined;
+            error?: SerializedError | FetchBaseQueryError | undefined;
             endpointName: string;
             startedTimeStamp: number;
             fulfilledTimeStamp?: number;
@@ -501,7 +501,7 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         } & {
             requestId: string;
             data?: unknown;
-            error?: FetchBaseQueryError | SerializedError | undefined;
+            error?: SerializedError | FetchBaseQueryError | undefined;
             endpointName: string;
             startedTimeStamp: number;
             fulfilledTimeStamp?: number;
@@ -518,14 +518,14 @@ export function davinci<ActionType extends ActionTypes = ActionTypes>(input: {
         } & Omit<{
             requestId: string;
             data?: unknown;
-            error?: FetchBaseQueryError | SerializedError | undefined;
+            error?: SerializedError | FetchBaseQueryError | undefined;
             endpointName: string;
             startedTimeStamp: number;
             fulfilledTimeStamp?: number;
         }, "error"> & Required<Pick<{
             requestId: string;
             data?: unknown;
-            error?: FetchBaseQueryError | SerializedError | undefined;
+            error?: SerializedError | FetchBaseQueryError | undefined;
             endpointName: string;
             startedTimeStamp: number;
             fulfilledTimeStamp?: number;
@@ -1187,8 +1187,8 @@ value: Record<string, unknown>;
 }, string>;
 
 // @public
-export const nodeCollectorReducer: Reducer<(TextCollector | SingleSelectCollector | PasswordCollector | ValidatedPasswordCollector | ValidatedBooleanCollector | ValidatedTextCollector | ProtectCollector | PollingCollector | FidoRegistrationCollector | FidoAuthenticationCollector | DeviceAuthenticationCollector | DeviceRegistrationCollector | PhoneNumberCollector | PhoneNumberExtensionCollector | UnknownCollector | IdpCollector | FlowCollector | SubmitCollector | ReadOnlyCollector | RichTextCollector | QrCodeCollector | AgreementCollector | MultiSelectCollector | ActionCollector<"ActionCollector"> | SingleValueCollector<"SingleValueCollector">)[]> & {
-    getInitialState: () => (TextCollector | SingleSelectCollector | PasswordCollector | ValidatedPasswordCollector | ValidatedBooleanCollector | ValidatedTextCollector | ProtectCollector | PollingCollector | FidoRegistrationCollector | FidoAuthenticationCollector | DeviceAuthenticationCollector | DeviceRegistrationCollector | PhoneNumberCollector | PhoneNumberExtensionCollector | UnknownCollector | IdpCollector | FlowCollector | SubmitCollector | ReadOnlyCollector | RichTextCollector | QrCodeCollector | AgreementCollector | MultiSelectCollector | ActionCollector<"ActionCollector"> | SingleValueCollector<"SingleValueCollector">)[];
+export const nodeCollectorReducer: Reducer<(ValidatedBooleanCollector | TextCollector | SingleSelectCollector | ValidatedTextCollector | PasswordCollector | ValidatedPasswordCollector | MultiSelectCollector | PhoneNumberExtensionCollector | DeviceAuthenticationCollector | DeviceRegistrationCollector | PhoneNumberCollector | IdpCollector | SubmitCollector | FlowCollector | QrCodeCollector | ReadOnlyCollector | RichTextCollector | AgreementCollector | UnknownCollector | ProtectCollector | FidoRegistrationCollector | FidoAuthenticationCollector | PollingCollector | ActionCollector<"ActionCollector"> | SingleValueCollector<"SingleValueCollector">)[]> & {
+    getInitialState: () => (ValidatedBooleanCollector | TextCollector | SingleSelectCollector | ValidatedTextCollector | PasswordCollector | ValidatedPasswordCollector | MultiSelectCollector | PhoneNumberExtensionCollector | DeviceAuthenticationCollector | DeviceRegistrationCollector | PhoneNumberCollector | IdpCollector | SubmitCollector | FlowCollector | QrCodeCollector | ReadOnlyCollector | RichTextCollector | AgreementCollector | UnknownCollector | ProtectCollector | FidoRegistrationCollector | FidoAuthenticationCollector | PollingCollector | ActionCollector<"ActionCollector"> | SingleValueCollector<"SingleValueCollector">)[];
 };
 
 // @public (undocumented)
@@ -1671,6 +1671,8 @@ export type SingleCheckboxField = {
     label: string;
     required: boolean;
     errorMessage?: string;
+    appearance: string;
+    richContent?: RichContent;
 };
 
 // @public (undocumented)
@@ -1924,7 +1926,13 @@ index?: number;
 export type Updater<T = unknown> = (value: CollectorValueType<T>, index?: number) => InternalErrorResponse | null;
 
 // @public (undocumented)
-export type ValidatedBooleanCollector = ValidatedSingleValueCollectorWithValue<'ValidatedBooleanCollector', boolean>;
+export interface ValidatedBooleanCollector extends ValidatedSingleValueCollectorWithValue<'ValidatedBooleanCollector', boolean> {
+    // (undocumented)
+    output: ValidatedSingleValueCollectorWithValue<'ValidatedBooleanCollector', boolean>['output'] & {
+        appearance: string;
+        richContent?: CollectorRichContent;
+    };
+}
 
 // @public (undocumented)
 export type ValidatedField = {