@mindbill/react 0.24.0 → 0.26.0

package/README.md

@@ -8,7 +8,7 @@ npm install @mindbill/react @mindbill/node
 
 ## Connected lifecycle
 
-`ConnectedBillLifecycle` starts after `BillSubmissionForm` atomically submits an immutable bill. It owns the submitted-to-closed progress rail, a read-only rendering of the exact submitted snapshot, server-owned human-readable history, packet download, EORs, payment posting, Second Bill Review, close, and reopen. The only persistent header action is **Download packet**; status-dependent actions appear in the details view when MindBill makes them available.
+`ConnectedBillLifecycle` starts after `BillSubmissionForm` atomically submits an immutable bill. It owns the submitted-to-closed progress rail, a read-only rendering of the exact submitted snapshot, server-owned human-readable history, packet download, EORs, payment posting, Second Bill Review, close, and reopen. The only persistent header action is **Download packet**; status-dependent actions open in a compact action sheet when MindBill makes them available.
 
 ```tsx
 import { ConnectedBillLifecycle } from "@mindbill/react";
@@ -83,7 +83,7 @@ The public lifecycle is `Submitted → Accepted → Processed → Closed`. Rejec
 
 ## Read-only bill details
 
-Use `BillReadOnlyForm` when you already loaded `BillLifecycleData` and only need the immutable detail surface. It uses the same section order and responsive layout as `BillSubmissionForm`, but renders values, calculated fees, and attachments without form controls.
+Use `BillReadOnlyForm` when you already loaded `BillLifecycleData` and only need the immutable detail surface. It uses the same section order and responsive layout as `BillSubmissionForm`, but renders values, calculated fees, routing details, and attachments without form controls. Its claims-administrator name is the canonical directory selection from the submitted delivery snapshot; selecting it opens the available contact and delivery details.
 
 ```tsx
 import { BillReadOnlyForm } from "@mindbill/react";
@@ -154,6 +154,7 @@ The component includes the interaction model, not just the markup:
 - complete, server-backed ICD-10 search with an alphabetized 100-code first page, automatic 100-code scroll paging, common-injury quick picks, and removable chips;
 - canonical claims-administrator matching through the authenticated MindBill payer directory: exact aliases select automatically, while fuzzy matches show up to five explicit suggestions with claim-number pattern evidence;
 - QME, AME, and Psych QME evaluation modes with medical-legal modifier defaults; Psych QME also seeds `Z04.6` when no more specific diagnosis was supplied, and exposes it as a Psych quick pick;
+- a searchable rendering-provider taxonomy combobox that accepts either a human-readable specialty search or an exact 10-character taxonomy code;
 - searchable workers-comp procedure/modifier controls, medical-legal fee-schedule amounts, totals, valid manual CPT/HCPCS entry, and an automatically maintained empty line;
 - removable source documents with new-tab previews, a locked auto-attached practice W-9, and a full-width click, panel-drop, or whole-page PDF upload area. Med-legal mode assigns every document to `J4 - Med-Legal Report` without showing another control; professional mode shows the complete searchable PWK01 report-type directory. Override that presentation with `attachmentReportTypeMode`, `attachmentReportTypes`, and `defaultAttachmentReportType`.
 
@@ -161,6 +162,8 @@ Partners supply tenant-specific bootstrap data, one short-lived browser session
 
 Validation is component-owned as well. A missing routing payer is highlighted immediately; Submit highlights every invalid control with a specific message, focuses and scrolls to the first problem, and continues validating as the user corrects the form.
 
+The complete immutable snapshot requires patient identity and address; employer, injury date, service date, and a canonical claims-administrator directory selection; at least one ICD-10 diagnosis and procedure line; billing provider name, Tax ID, NPI, phone, and address; rendering provider name, NPI, and taxonomy; and service address plus place-of-service code. Address line 2 remains optional. License number, license state, specialty, and service-facility display name are not requested by the standard component. For California workers-comp CMS-1500 output, `renderingProvider.taxonomy` is the 10-character provider taxonomy placed in shaded Box 24J with qualifier `ZZ`; it is not replaced by the physician license number.
+
 `BILL_SUBMISSION_REQUIRED_FIELDS` and `validateBillSubmission` expose the same contract for tests and non-visual integrations. The component never creates a draft; `onSubmitted` fires only after MindBill accepts a locally valid immutable snapshot. The legacy `onSubmit` escape hatch remains optional for unusual deployments, but connected integrations should omit it so the library owns the complete contract.
 
 `BillReviewForm` remains available for legacy integrations that already own a custom review model. New integrations should use `BillSubmissionForm`.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { MindBillAppearance, MindBillEventDetail, MindBillErrorDetail } from '@mindbill/embed';
 export { MindBillAppearance, MindBillErrorDetail, MindBillEventDetail } from '@mindbill/embed';
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { BillReviewData as BillReviewData$1, BillReviewAttachment as BillReviewAttachment$1, BrowserBillSubmissionResult, BillLifecycleSessionProvider, BillReviewPayer as BillReviewPayer$1, BrowserBillSubmissionDocument, BillLifecycleAction, BillLifecycleDelivery, BillPaymentRecord, BillRemittanceSummary, BillLifecycleData, BillLifecycleClientOptions, BillLifecycleClient, BillEorDocument } from '@mindbill/browser';
+import { BillReviewData as BillReviewData$1, BillLifecycleDelivery, BillReviewAttachment as BillReviewAttachment$1, BrowserBillSubmissionResult, BillLifecycleSessionProvider, BillReviewPayer as BillReviewPayer$1, BrowserBillSubmissionDocument, BillLifecycleAction, BillPaymentRecord, BillRemittanceSummary, BillLifecycleData, BillLifecycleClientOptions, BillLifecycleClient, BillEorDocument } from '@mindbill/browser';
 export { BillActivityRecord, BillEorDocument, BillLifecycleAction, BillLifecycleActionId, BillLifecycleClient, BillLifecycleClientOptions, BillLifecycleData, BillLifecycleDelivery, BillLifecycleSession, BillLifecycleSessionProvider, BillLifecycleSessionRequest, BillPaymentRecord, BillRemittanceSummary, BrowserBillSubmissionResult, CloseBillInput, PostBillPaymentInput, ReopenBillInput, SubmitSecondReviewInput, createBillLifecycleClient } from '@mindbill/browser';
 
 type MindBillThemePreset = "mindbill" | "qme-companion" | "orange-bright" | "clinical-blue";
@@ -347,7 +347,9 @@ type BillStatusAction = {
 declare function BillStatusSummary({ status, submittedAt, agingDays, updatedAt, totalCharge, totalPaid, balanceDue, actions, className, style, appearance }: BillStatusSummaryProps): ReactElement;
 
 type BillReadOnlyFormProps = {
-    data: BillReviewData$1;
+    data: BillReviewData$1 & {
+        delivery?: BillLifecycleDelivery;
+    };
     appearance?: MindBillReactAppearance;
     className?: string;
     style?: CSSProperties;
@@ -367,6 +369,7 @@ declare const BILL_SUBMISSION_REPORT_TYPES: readonly BillSubmissionReportTypeOpt
 type BillSubmissionEvaluationType = "qme" | "ame" | "psych_qme";
 type BillSubmissionAddress = {
     line1: string;
+    line2?: string;
     city: string;
     state: string;
     postalCode: string;
@@ -384,6 +387,10 @@ type BillSubmissionModifierOption = {
     code: string;
     description: string;
 };
+type BillSubmissionTaxonomyOption = {
+    code: string;
+    description: string;
+};
 type BillSubmissionPostalPlace = {
     city: string;
     state: string;
@@ -455,6 +462,36 @@ type BillSubmissionInput = {
         diagnosisPointers?: number[];
     }>;
 };
+/** A validated, submission-ready bill. The form accepts partial provider data while editing,
+ * but only emits this complete contract after every required field has passed validation. */
+type CompleteBillSubmissionInput = Omit<BillSubmissionInput, "claim" | "billingProvider" | "renderingProvider" | "serviceLocation" | "diagnoses" | "serviceLines"> & {
+    claim: BillSubmissionInput["claim"] & {
+        employer: string;
+        dateOfInjury: string;
+        claimsAdministrator: {
+            id: string;
+            name: string;
+        };
+    };
+    billingProvider: {
+        name: string;
+        taxId: string;
+        npi: string;
+        phone: string;
+        address: BillSubmissionAddress;
+    };
+    renderingProvider: NonNullable<BillSubmissionInput["renderingProvider"]> & {
+        name: string;
+        npi: string;
+        taxonomy: string;
+    };
+    serviceLocation: NonNullable<BillSubmissionInput["serviceLocation"]> & {
+        address: BillSubmissionAddress;
+        placeOfServiceCode: string;
+    };
+    diagnoses: string[];
+    serviceLines: BillSubmissionInput["serviceLines"];
+};
 type BillSubmissionSourceAttachment = {
     id: string;
     fileName: string;
@@ -475,7 +512,7 @@ type BillSubmissionUpload = {
     reportTypeCode?: string;
 };
 type BillSubmissionFormValue = {
-    bill: BillSubmissionInput;
+    bill: CompleteBillSubmissionInput;
     sourceAttachmentIds: string[];
     sourceAttachmentReportTypes: Record<string, string>;
     uploads: BillSubmissionUpload[];
@@ -501,6 +538,8 @@ type BillSubmissionFormProps = {
     onLookupPostalCode?: (postalCode: string) => Promise<BillSubmissionPostalPlace | null>;
     procedureOptions?: BillSubmissionProcedureOption[];
     modifierOptions?: BillSubmissionModifierOption[];
+    /** Common NUCC provider taxonomies are bundled; supplied values extend or replace matching codes. */
+    taxonomyOptions?: BillSubmissionTaxonomyOption[];
     /** Auto hides and forces J4 for med-legal bills; treatment bills show the full report-type directory. */
     attachmentReportTypeMode?: BillSubmissionAttachmentReportTypeMode;
     attachmentReportTypes?: readonly BillSubmissionReportTypeOption[];
@@ -518,7 +557,7 @@ type BillSubmissionFormProps = {
      */
     children?: ReactNode;
 };
-declare const BILL_SUBMISSION_REQUIRED_FIELDS: readonly ["patient.firstName", "patient.lastName", "patient.dateOfBirth", "patient.address.line1", "patient.address.city", "patient.address.state", "patient.address.postalCode", "claim.claimNumber", "claim.claimsAdministrator", "service.date", "diagnoses[]", "serviceLines[].code", "serviceLines[].units"];
+declare const BILL_SUBMISSION_REQUIRED_FIELDS: readonly ["patient.firstName", "patient.lastName", "patient.dateOfBirth", "patient.address.line1", "patient.address.city", "patient.address.state", "patient.address.postalCode", "claim.claimNumber", "claim.employer", "claim.dateOfInjury", "claim.claimsAdministrator", "service.date", "billingProvider.name", "billingProvider.taxId", "billingProvider.npi", "billingProvider.phone", "billingProvider.address.line1", "billingProvider.address.city", "billingProvider.address.state", "billingProvider.address.postalCode", "renderingProvider.name", "renderingProvider.npi", "renderingProvider.taxonomy", "serviceLocation.placeOfServiceCode", "serviceLocation.address.line1", "serviceLocation.address.city", "serviceLocation.address.state", "serviceLocation.address.postalCode", "diagnoses[]", "serviceLines[].code", "serviceLines[].units"];
 type BillSubmissionValidation = {
     valid: boolean;
     fieldErrors: Record<string, string>;
@@ -550,11 +589,13 @@ declare function BillSubmissionProvidersSection(): ReactElement;
 declare function BillSubmissionServiceLinesSection(): ReactElement;
 declare function BillSubmissionAttachmentsSection(): ReactElement;
 declare function BillSubmissionActions(): ReactElement;
-declare function BillSubmissionForm({ initialBill, attachments, onSubmit, onSubmitted, getSession, sessionEndpoint, apiBaseUrl, fetch: fetchOverride, onSearchClaimsAdministrators, diagnosisOptions, onSearchDiagnoses, onLookupPostalCode, procedureOptions, modifierOptions, attachmentReportTypeMode, attachmentReportTypes, defaultAttachmentReportType, appearance, className, style, disabled, submitLabel, heading, description, children, }: BillSubmissionFormProps): ReactElement;
+declare function BillSubmissionForm({ initialBill, attachments, onSubmit, onSubmitted, getSession, sessionEndpoint, apiBaseUrl, fetch: fetchOverride, onSearchClaimsAdministrators, diagnosisOptions, onSearchDiagnoses, onLookupPostalCode, procedureOptions, modifierOptions, taxonomyOptions, attachmentReportTypeMode, attachmentReportTypes, defaultAttachmentReportType, appearance, className, style, disabled, submitLabel, heading, description, children, }: BillSubmissionFormProps): ReactElement;
 
 /** Public-domain and MindBill-owned metadata. CPT descriptions are intentionally limited to the curated catalog. */
 declare const DEFAULT_BILL_SUBMISSION_PROCEDURES: BillSubmissionProcedureOption[];
 declare const DEFAULT_BILL_SUBMISSION_MODIFIERS: BillSubmissionModifierOption[];
+/** Common NUCC provider taxonomies. Consumers can extend this catalog through taxonomyOptions. */
+declare const DEFAULT_BILL_SUBMISSION_TAXONOMIES: BillSubmissionTaxonomyOption[];
 declare const BILL_SUBMISSION_DIAGNOSIS_QUICK_PICKS: Array<BillSubmissionDiagnosisOption & {
     label: string;
 }>;
@@ -812,4 +853,4 @@ type MindBillWidgetProps = {
 declare function MindBillBillTimeline(props: MindBillWidgetProps): ReactElement;
 declare function MindBillBillReview(props: MindBillWidgetProps): ReactElement;
 
-export { BILL_SUBMISSION_DIAGNOSIS_QUICK_PICKS, BILL_SUBMISSION_DOCUMENT_TYPES, BILL_SUBMISSION_REPORT_TYPES, BILL_SUBMISSION_REQUIRED_FIELDS, type BillActivityEvent, BillActivityTimeline, type BillActivityTimelineProps, type BillAgingBucket, type BillAgingBucketId, BillAgingSummary, type BillAgingSummaryProps, BillLifecycleActions, type BillLifecycleActionsProps, BillLifecycleProgress, type BillLifecycleProgressProps, type BillLifecycleStage, BillList, type BillListProps, BillPayerContactCard, type BillPayerContactCardProps, BillPaymentLedger, type BillPaymentLedgerProps, BillReadOnlyForm, type BillReadOnlyFormProps, BillRemittanceCard, type BillRemittanceCardProps, type BillReviewAttachment, type BillReviewBillingProvider, type BillReviewClinician, type BillReviewData, type BillReviewDocumentType, type BillReviewDraft, type BillReviewFeatures, BillReviewForm, type BillReviewFormProps, type BillReviewLineItem, type BillReviewLocation, type BillReviewPayer, type BillReviewSaveInput, BillSnapshotSummary, type BillSnapshotSummaryProps, type BillStatusAction, type BillStatusClient, type BillStatusClientOptions, type BillStatusData, type BillStatusSession, type BillStatusSessionProvider, type BillStatusSessionRequest, BillStatusSummary, type BillStatusSummaryProps, BillSubmissionActions, type BillSubmissionAddress, type BillSubmissionAttachmentReportTypeMode, BillSubmissionAttachmentsSection, BillSubmissionClaimSection, type BillSubmissionDiagnosisOption, type BillSubmissionDocumentType, type BillSubmissionEvaluationType, BillSubmissionForm, type BillSubmissionFormProps, type BillSubmissionFormValue, BillSubmissionHeader, type BillSubmissionInput, type BillSubmissionModifierOption, BillSubmissionPatientSection, type BillSubmissionPostalPlace, type BillSubmissionProcedureOption, BillSubmissionProvidersSection, type BillSubmissionReportTypeOption, type BillSubmissionRoute, type BillSubmissionSectionId, BillSubmissionServiceLinesSection, type BillSubmissionSourceAttachment, type BillSubmissionUpload, type BillSubmissionValidation, type BillingComponentProps, BillingDashboard, type BillingDashboardBill, type BillingDashboardProps, type BillingDashboardSummary, BillingReport, type BillingReportDimension, type BillingReportProps, type BillingReportRow, ConnectedBillLifecycle, type ConnectedBillLifecycleProps, ConnectedBillStatus, type ConnectedBillStatusProps, DEFAULT_BILL_SUBMISSION_MODIFIERS, DEFAULT_BILL_SUBMISSION_PROCEDURES, MED_LEGAL_REPORT_TYPE_CODE, MindBillBillReview, MindBillBillTimeline, type MindBillReactAppearance, type MindBillThemePreset, type MindBillWidgetProps, PSYCH_QME_DEFAULT_DIAGNOSIS, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, applyBillSubmissionEvaluationDiagnoses, applyBillSubmissionEvaluationModifiers, billActivityEventLabel, billAgingBucket, billAgingDays, billLifecycleDisplayLabel, billLifecycleStage, buildBillReviewSaveInput, buildBillingReportCsv, buildBillingReportRows, calculateBillSubmissionAllowedAmount, claimsAdministratorRecommendations, createBillStatusClient, ensureTrailingBillSubmissionLine, ensureTrailingProcedureLine, exactClaimsAdministratorMatch, formatBillSubmissionDate, mindBillAppearanceStyle, mindBillThemePresets, normalizeClaimsAdministratorName, parseBillSubmissionDate, prepareBillSubmissionDocuments, resolveMindBillAppearance, summarizeBillingDashboard, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };
+export { BILL_SUBMISSION_DIAGNOSIS_QUICK_PICKS, BILL_SUBMISSION_DOCUMENT_TYPES, BILL_SUBMISSION_REPORT_TYPES, BILL_SUBMISSION_REQUIRED_FIELDS, type BillActivityEvent, BillActivityTimeline, type BillActivityTimelineProps, type BillAgingBucket, type BillAgingBucketId, BillAgingSummary, type BillAgingSummaryProps, BillLifecycleActions, type BillLifecycleActionsProps, BillLifecycleProgress, type BillLifecycleProgressProps, type BillLifecycleStage, BillList, type BillListProps, BillPayerContactCard, type BillPayerContactCardProps, BillPaymentLedger, type BillPaymentLedgerProps, BillReadOnlyForm, type BillReadOnlyFormProps, BillRemittanceCard, type BillRemittanceCardProps, type BillReviewAttachment, type BillReviewBillingProvider, type BillReviewClinician, type BillReviewData, type BillReviewDocumentType, type BillReviewDraft, type BillReviewFeatures, BillReviewForm, type BillReviewFormProps, type BillReviewLineItem, type BillReviewLocation, type BillReviewPayer, type BillReviewSaveInput, BillSnapshotSummary, type BillSnapshotSummaryProps, type BillStatusAction, type BillStatusClient, type BillStatusClientOptions, type BillStatusData, type BillStatusSession, type BillStatusSessionProvider, type BillStatusSessionRequest, BillStatusSummary, type BillStatusSummaryProps, BillSubmissionActions, type BillSubmissionAddress, type BillSubmissionAttachmentReportTypeMode, BillSubmissionAttachmentsSection, BillSubmissionClaimSection, type BillSubmissionDiagnosisOption, type BillSubmissionDocumentType, type BillSubmissionEvaluationType, BillSubmissionForm, type BillSubmissionFormProps, type BillSubmissionFormValue, BillSubmissionHeader, type BillSubmissionInput, type BillSubmissionModifierOption, BillSubmissionPatientSection, type BillSubmissionPostalPlace, type BillSubmissionProcedureOption, BillSubmissionProvidersSection, type BillSubmissionReportTypeOption, type BillSubmissionRoute, type BillSubmissionSectionId, BillSubmissionServiceLinesSection, type BillSubmissionSourceAttachment, type BillSubmissionTaxonomyOption, type BillSubmissionUpload, type BillSubmissionValidation, type BillingComponentProps, BillingDashboard, type BillingDashboardBill, type BillingDashboardProps, type BillingDashboardSummary, BillingReport, type BillingReportDimension, type BillingReportProps, type BillingReportRow, ConnectedBillLifecycle, type ConnectedBillLifecycleProps, ConnectedBillStatus, type ConnectedBillStatusProps, DEFAULT_BILL_SUBMISSION_MODIFIERS, DEFAULT_BILL_SUBMISSION_PROCEDURES, DEFAULT_BILL_SUBMISSION_TAXONOMIES, MED_LEGAL_REPORT_TYPE_CODE, MindBillBillReview, MindBillBillTimeline, type MindBillReactAppearance, type MindBillThemePreset, type MindBillWidgetProps, PSYCH_QME_DEFAULT_DIAGNOSIS, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, applyBillSubmissionEvaluationDiagnoses, applyBillSubmissionEvaluationModifiers, billActivityEventLabel, billAgingBucket, billAgingDays, billLifecycleDisplayLabel, billLifecycleStage, buildBillReviewSaveInput, buildBillingReportCsv, buildBillingReportRows, calculateBillSubmissionAllowedAmount, claimsAdministratorRecommendations, createBillStatusClient, ensureTrailingBillSubmissionLine, ensureTrailingProcedureLine, exactClaimsAdministratorMatch, formatBillSubmissionDate, mindBillAppearanceStyle, mindBillThemePresets, normalizeClaimsAdministratorName, parseBillSubmissionDate, prepareBillSubmissionDocuments, resolveMindBillAppearance, summarizeBillingDashboard, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };