feat(benefits) - surface benefits x-jsf-presentation

example/src/Onboarding.tsx

@@ -15,12 +15,45 @@
   zendeskArticles,
 } from '@remoteoss/remote-flows';
 import React, { useState } from 'react';
+import { Card } from '@remoteoss/remote-flows/internals';
 import { ReviewOnboardingStep } from './ReviewOnboardingStep';
 import { OnboardingAlertStatuses } from './OnboardingAlertStatuses';
 import { RemoteFlows } from './RemoteFlows';
 import { AlertError } from './AlertError';
+import { sanitizeHtml } from '@remoteoss/remote-flows/internals';
 import './css/main.css';
 
+const BenefitsAboutSection = ({
+  description,
+  url,
+}: {
+  description: string;
+  url: string;
+}) => {
+  if (!description || !url) {
+    return null;
+  }
+  return (
+    <Card className='space-y-4 p-6 mb-4'>
+      <h2 className='text-xl font-semibold text-gray-900'>About</h2>
+      <div
+        className='prose prose-sm max-w-none text-xs text-gray-700 leading-relaxed space-y-4'
+        dangerouslySetInnerHTML={{ __html: sanitizeHtml(description) }}
+      />
+      <p className='text-xs text-gray-700 leading-relaxed space-y-4'>
+        Want more details on benefits?{' '}
+        <a
+          href={url}
+          className='inline-block text-blue-600 hover:text-blue-700 hover:underline text-xs mt-2'
+          target='_blank'
+          rel='noopener noreferrer'
+        >
+          Check our guide
+        </a>
+      </p>
+    </Card>
+  );
+};
 export const InviteSection = ({
   title,
   description,
@@ -68,10 +101,10 @@
         <>
           <SelectCountryStep
             onSubmit={(payload: SelectCountryFormPayload) =>
               console.log('payload', payload)
             }
             onSuccess={(response: SelectCountrySuccess) =>
               console.log('response', response)
             }
             onError={({
               error,
@@ -96,10 +129,10 @@
           />
           <BasicInformationStep
             onSubmit={(payload: BasicInformationFormPayload) =>
               console.log('payload', payload)
             }
             onSuccess={(data: EmploymentCreationResponse) =>
               console.log('data', data)
             }
             onError={({ error, fieldErrors }) =>
               setErrors({ apiError: error.message, fieldErrors })
@@ -127,7 +160,7 @@
         <>
           <EngagementAgreementDetailsStep
             onSubmit={(payload: EngagementAgreementDetailsFormPayload) =>
               console.log('payload', payload)
             }
             onSuccess={(data: SuccessResponse) => console.log('data', data)}
             onError={({ error, fieldErrors }) =>
@@ -188,9 +221,17 @@
         </>
       );
 
-    case 'benefits':
+    case 'benefits': {
+      // Example: Access schema-level presentation metadata
+      const benefitsPresentation = onboardingBag.meta.presentation;
+
       return (
         <div className='benefits-container'>
+          <BenefitsAboutSection
+            description={benefitsPresentation?.description as string}
+            url={benefitsPresentation?.url as string}
+          />
+
           <BenefitsStep
             onSubmit={(payload: BenefitsFormPayload) =>
               console.log('payload', payload)
@@ -204,6 +245,7 @@
             }) => setErrors({ apiError: error.message, fieldErrors })}
             onSuccess={(data: SuccessResponse) => console.log('data', data)}
           />
+
           <AlertError errors={errors} />
           <div className='buttons-container'>
             <BackButton
@@ -221,6 +263,7 @@
           </div>
         </div>
       );
+    }
     case 'review':
       return (
         <ReviewOnboardingStep

src/common/createHeadlessForm.tsx

@@ -70,6 +70,9 @@ export const createHeadlessForm = (
   return {
     meta: {
       'x-jsf-fieldsets': jsfSchema['x-jsf-fieldsets'] as JSFFieldset,
+      'x-jsf-presentation': jsfSchema['x-jsf-presentation'] as
+        | Record<string, unknown>
+        | undefined,
     },
     ...baseCreateHeadlessForm(jsfSchema, {
       initialValues,

src/flows/ContractorOnboarding/hooks.tsx

@@ -639,6 +639,22 @@ export const useContractorOnboarding = ({
     review: null,
   };
 
+  const stepPresentation: Record<
+    StepKeys,
+    Record<string, unknown> | null | undefined
+  > = {
+    select_country: selectCountryForm?.meta?.['x-jsf-presentation'],
+    basic_information: basicInformationForm?.meta?.['x-jsf-presentation'],
+    pricing_plan:
+      selectContractorSubscriptionForm?.meta?.['x-jsf-presentation'],
+    eligibility_questionnaire:
+      eligibilityQuestionnaireForm?.meta?.['x-jsf-presentation'],
+    contract_details:
+      contractorOnboardingDetailsForm?.meta?.['x-jsf-presentation'],
+    contract_preview: signatureSchemaForm?.meta?.['x-jsf-presentation'],
+    review: null,
+  };
+
   const {
     country,
     basic_information: employmentBasicInformation = {},
@@ -1276,6 +1292,7 @@ export const useContractorOnboarding = ({
     meta: {
       fields: fieldsMetaRef.current,
       fieldsets: stepFieldsWithFlatFieldsets[stepState.currentStep.name],
+      presentation: stepPresentation[stepState.currentStep.name],
     },
 
     /**

src/flows/Onboarding/hooks.tsx

@@ -570,6 +570,19 @@ export const useOnboarding = ({
     review: null,
   };
 
+  const stepPresentation: Record<
+    StepKeys,
+    Record<string, unknown> | null | undefined
+  > = {
+    select_country: selectCountryForm?.meta?.['x-jsf-presentation'],
+    basic_information: basicInformationForm?.meta?.['x-jsf-presentation'],
+    engagement_agreement_details:
+      engagementAgreementDetailsSchema?.meta?.['x-jsf-presentation'],
+    contract_details: contractDetailsForm?.meta?.['x-jsf-presentation'],
+    benefits: benefitOffersSchema?.meta?.['x-jsf-presentation'],
+    review: null,
+  };
+
   const {
     country,
     basic_information: employmentBasicInformation = {},
@@ -1086,6 +1099,7 @@ export const useOnboarding = ({
     meta: {
       fields: fieldsMetaRef.current,
       fieldsets: stepFieldsWithFlatFieldsets[stepState.currentStep.name],
+      presentation: stepPresentation[stepState.currentStep.name],
     },
 
     /**

src/flows/Onboarding/tests/OnboardingFlow.test.tsx

@@ -2566,4 +2566,120 @@ describe('OnboardingFlow', () => {
       ).toBeInTheDocument();
     });
   });
+
+  it('should include description, fine_print, and benefits_service_fee in benefits presentation', async () => {
+    let capturedPresentation: Record<string, unknown> | null | undefined = null;
+
+    mockRender.mockImplementation(
+      ({ onboardingBag, components }: OnboardingRenderProps) => {
+        const currentStepIndex = onboardingBag.stepState.currentStep.index;
+        const steps: Record<number, string> = {
+          [0]: 'Basic Information',
+          [1]: 'Contract Details',
+          [2]: 'Benefits',
+          [3]: 'Review',
+        };
+
+        if (onboardingBag.stepState.currentStep.name === 'benefits') {
+          capturedPresentation = onboardingBag.meta.presentation;
+        }
+
+        if (onboardingBag.isLoading) {
+          return <div data-testid='spinner'>Loading...</div>;
+        }
+
+        return (
+          <>
+            <h1>Step: {steps[currentStepIndex]}</h1>
+            <MultiStepFormWithoutCountry
+              onboardingBag={onboardingBag}
+              components={components}
+            />
+          </>
+        );
+      },
+    );
+
+    render(
+      <OnboardingFlow
+        employmentId={generateUniqueEmploymentId()}
+        skipSteps={['select_country']}
+        {...defaultProps}
+      />,
+      { wrapper: TestProviders },
+    );
+
+    await waitForElementToBeRemoved(() => screen.getByTestId('spinner'));
+
+    let nextButton = screen.getByText(/Next Step/i);
+    nextButton.click();
+    await screen.findByText(/Step: Contract Details/i);
+
+    nextButton = screen.getByText(/Next Step/i);
+    nextButton.click();
+    await screen.findByText(/Step: Benefits/i);
+
+    expect(capturedPresentation).toEqual({
+      benefits_service_fee: {
+        amount: 15.0,
+        currency: 'USD',
+      },
+      description:
+        'We offer our employees supplemental benefits - Meal and Health Insurance (In partnership with Advance Care/Tranquilidade and Coverflex)',
+      fine_print:
+        'New: Health Insurance is now optional for new hires in Portugal.\r\nPlease note that all local payroll deductions for required coverages are included in the TCE.\r\nAny pricing changes will be communicated in advance of updated billing.',
+      url: 'https://remote.com/benefits-guide/portugal',
+    });
+  });
+
+  it('should have null or undefined presentation for basic_information step', async () => {
+    let capturedBasicInfoPresentation:
+      | Record<string, unknown>
+      | null
+      | undefined = undefined;
+
+    mockRender.mockImplementation(
+      ({ onboardingBag, components }: OnboardingRenderProps) => {
+        const currentStepIndex = onboardingBag.stepState.currentStep.index;
+        const steps: Record<number, string> = {
+          [0]: 'Basic Information',
+          [1]: 'Contract Details',
+          [2]: 'Benefits',
+          [3]: 'Review',
+        };
+
+        if (onboardingBag.stepState.currentStep.name === 'basic_information') {
+          capturedBasicInfoPresentation = onboardingBag.meta.presentation;
+        }
+
+        if (onboardingBag.isLoading) {
+          return <div data-testid='spinner'>Loading...</div>;
+        }
+
+        return (
+          <>
+            <h1>Step: {steps[currentStepIndex]}</h1>
+            <MultiStepFormWithoutCountry
+              onboardingBag={onboardingBag}
+              components={components}
+            />
+          </>
+        );
+      },
+    );
+
+    render(
+      <OnboardingFlow
+        employmentId={generateUniqueEmploymentId()}
+        skipSteps={['select_country']}
+        {...defaultProps}
+      />,
+      { wrapper: TestProviders },
+    );
+
+    await waitForElementToBeRemoved(() => screen.getByTestId('spinner'));
+    await screen.findByText(/Step: Basic Information/i);
+
+    expect(capturedBasicInfoPresentation).toBeUndefined();
+  });
 });

src/flows/types.ts

@@ -107,5 +107,6 @@ type FormResult = FormResultNext | FormResultLegacy;
 export type JSONSchemaFormResultWithFieldsets = FormResult & {
   meta: {
     'x-jsf-fieldsets': JSFFieldset;
+    'x-jsf-presentation'?: Record<string, unknown>;
   };
 };

src/internals.ts

@@ -8,7 +8,7 @@
  */
 
 // Internal utilities
-export { cn } from './lib/utils';
+export { cn, sanitizeHtml } from './lib/utils';
 
 // UI Components for internal use
 export { Button, buttonVariants } from './components/ui/button';