@heudia/network-referral-form

Lit web component for the AccessMeCare Network Referral flow. Replaces the SurveyJS form on Insights' /network-referral route with a HIPAA-/GDPR-aware MFA bundle that ships English + Spanish out of the box, emits a structured submit event, and provides a service factory the host can use to persist to Firestore (or swap for a mock).

Install

pnpm add @heudia/network-referral-form
# If you plan to use FirestoreNetworkReferralService:
pnpm add firebase

firebase is an optional peer dependency — hosts that only use the in-memory mock service don't need to install it.

Mounting

import '@heudia/network-referral-form';
import { createNetworkReferralService } from '@heudia/network-referral-form';

const service = createNetworkReferralService({ firebaseConfig });

document.querySelector('heudia-network-referral-form')
  ?.addEventListener('submit', async (e) => {
    const { payload, locale } = (e as CustomEvent).detail;
    const record = await service.submit(payload, {
      orgUuid: receivingOrgUuid,
      locale,
    });
    console.log('persisted', record.id);
  });

<heudia-network-referral-form
  org-name="Well Life Outreach"
  locale="es"
></heudia-network-referral-form>

Attributes / properties

| Attribute / property | Type | Notes | | --- | --- | --- | | org-name | string | Pre-fills the "Receiving Organization" field; the user can still edit it. | | locale | 'en' \| 'es' | Active locale. Changing it at runtime flips every label, validation message, and choice. | | initialPayload (property only) | Partial<NetworkReferralPayload> | Seed for prefill / drafts. Must be set via JS, not an attribute. |

Events

| Event | Detail | When | | --- | --- | --- | | submit | { payload, locale, submittedAt } | Validation passes and the user clicks Submit. Bubbles + composed. | | nrf:change | { name, value } | Any field change. Useful for analytics / autosave. Bubbles + composed. |

Form shape (37 fields)

| Section | Fields | | --- | --- | | Client | first/middle/last name, DOB, legal-rep flag, email, phone, preferred contact methods (multi), org-ID-by-name flag | | Client address | street, ext, city, state, ZIP | | Representative (conditional on legal-rep = Yes) | first/middle/last name, DOB, email, phone, relationship, address-same-as-client flag, address fields (when distinct) | | Referral details | receiving org, services (multi), reasons (multi), notes | | Consent | provided flag, full name, opt-ins (multi), method, date, verification |

Required-ness, choices, and field order mirror docs/referral/forms/network-referral-form-model.json in the MFA repo.

i18n

Translations live in content/{en,es}.json and load via i18next. The element exposes them through an internal I18nController; every primitive auto-rerenders on languageChanged.

To add a third locale at the host level without forking:

import { getOrInitNetworkReferralI18n } from '@heudia/network-referral-form/i18n';
import fr from './my-fr-bundle.json';

const i18n = getOrInitNetworkReferralI18n();
i18n.addResourceBundle('fr', 'translation', fr);
// Then set `locale="fr"` on the element.

Services

INetworkReferralService is the persistence boundary, with two ready implementations and a factory that picks between them.

import {
  createNetworkReferralService,
  MockNetworkReferralService,
  FirestoreNetworkReferralService,
  type INetworkReferralService,
} from '@heudia/network-referral-form';

const dev: INetworkReferralService = createNetworkReferralService({ mockMode: true });
const prod = createNetworkReferralService({
  firebaseConfig,                       // any existing app instance is reused
  collectionName: 'network-referrals',  // optional override
});

| Implementation | Use case | | --- | --- | | MockNetworkReferralService | example app, Storybook, unit tests — keeps records in memory | | FirestoreNetworkReferralService | production — dynamic imports of firebase/app + firebase/firestore; reuses the host's existing app if one is initialized |

createNetworkReferralService falls back to the mock + logs a warning when neither mockMode nor firebaseConfig is supplied.

Demo

A working React demo is available in the MFA monorepo:

pnpm --filter heudia-react-example dev
# open the "Network Referral" tab

The demo shows the locale toggle, the sample-data prefill, and the round-trip from submit → service → persisted record.

Reference

• docs/referral/forms/network-referral-form-requirements.md — top-level requirements
• docs/referral/forms/network-referral-form-model.json — field schema (SurveyJS shape)
• docs/referral/forms/network-referral-survey-answers.md — sample completed payload
• docs/referral/forms/network-referral-form-implementation.md — package architecture + design decisions
• docs/referral/forms/network-referral-form-insights-integration.md — Insights replacement guide