@mindbill/react 0.27.1 → 0.28.1

package/README.md

@@ -8,7 +8,7 @@ npm install @mindbill/react @mindbill/node
 
 ## Connected lifecycle
 
-`ConnectedBillLifecycle` starts after `BillSubmissionForm` atomically submits an immutable bill. Its only bill input is `billId`; `getSession` returns the short-lived token. The component fetches the submitted snapshot, progress, human-readable history, EOR/remittance amounts, payments, and available actions from MindBill. Do not pass lifecycle seed data or duplicate this state in the host app. The only persistent header action is **Download packet**; status-dependent actions open in a compact action sheet when MindBill makes them available.
+`ConnectedBillLifecycle` starts after `BillSubmissionForm` atomically submits an immutable bill. Its only bill input is `billId`; `getSession` returns the short-lived token. The component fetches the submitted snapshot, progress, human-readable history, EOR/remittance amounts, payments, and available actions from MindBill. Do not pass lifecycle seed data or duplicate this state in the host app. The only persistent header action is **Download packet**; status-dependent actions remain visible in a sticky bottom action bar when MindBill makes them available. Actions that require input open a focused form dialog.
 
 ```tsx
 import { ConnectedBillLifecycle } from "@mindbill/react";
@@ -20,6 +20,11 @@ import { ConnectedBillLifecycle } from "@mindbill/react";
 />
 ```
 
+Sandbox and live responses use the same component contract. Simulation controls
+are hidden by default, including when the connected organization is a sandbox.
+Only a dedicated developer playground should opt in with
+`sandboxControls={true}`; production applications should omit the prop.
+
 ## Appearance
 
 Choose a complete preset, then override only the tokens your design system owns. The preset applies to review, payer search, attachments, submission, status, EOR, payment, denial, resubmission, and close states.
@@ -79,11 +84,11 @@ import { ConnectedBillStatus } from "@mindbill/react";
 
 Use `useBillStatus({ billId })` when you want to render custom status UI. It returns `data`, `error`, `isLoading`, `isRefreshing`, and `refresh`. Use `createBillStatusClient` outside React.
 
-The public lifecycle is `Submitted → Accepted → Processed → Closed`. Rejections and denials remain detailed states inside the Processed stage so the progress rail stays stable while the action sheet explains what the user can do next. Partner APIs and components do not expose draft or queued states.
+The public lifecycle is `Submitted → Accepted → Processed → Closed`. Rejections and denials remain detailed states inside the Processed stage so the progress rail stays stable while the sticky action bar explains what the user can do next. Partner APIs and components do not expose draft or queued states. Once the payer responds, the Details tab leads with one consolidated Explanation of Review reconciliation surface: billed, allowed, payer-reported payment, posted payment, penalty and interest, balance, denial reason, payment records, and the EOR document.
 
 ## 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, 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.
+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 a responsive directory dialog with Main, Bill Review, Authorization, Mailing Address, and Claim Number Pattern tabs when those fields are available from the API.
 
 ```tsx
 import { BillReadOnlyForm } from "@mindbill/react";

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 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, 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';
+import { BillReviewData as BillReviewData$1, BillLifecycleDelivery, BillReviewAttachment as BillReviewAttachment$1, BrowserBillSubmissionResult, BillLifecycleSessionProvider, BillReviewPayer as BillReviewPayer$1, BrowserBillSubmissionDocument, BillRemittanceSummary, BillEorDocument, BillPaymentRecord, BillLifecycleAction, BillLifecycleData, BillLifecycleClientOptions, BillLifecycleClient } from '@mindbill/browser';
+export { BillActivityRecord, BillClaimsAdministratorContact, BillClaimsAdministratorDirectory, BillClaimsAdministratorMailingAddress, BillClaimsAdministratorPattern, 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";
 type MindBillReactAppearance = MindBillAppearance & {
@@ -795,6 +795,18 @@ declare function BillSnapshotSummary({ bill, patient, injury, delivery, appearan
 type BillRemittanceCardProps = SurfaceProps & {
     remittance: BillRemittanceSummary;
 };
+type BillExplanationOfReviewProps = SurfaceProps & {
+    remittance: BillRemittanceSummary;
+    eors: readonly BillEorDocument[];
+    payments: readonly BillPaymentRecord[];
+    submittedAt?: string | null;
+    onOpenEor?: (document: BillEorDocument) => void | Promise<void>;
+};
+/**
+ * A consolidated payer-response surface: financial summary, denial context,
+ * EOR documents, and posted payments in one familiar reconciliation view.
+ */
+declare function BillExplanationOfReview({ remittance, eors, payments, submittedAt, onOpenEor, appearance, className, style, }: BillExplanationOfReviewProps): ReactElement;
 declare function BillRemittanceCard({ remittance, appearance, className, style }: BillRemittanceCardProps): ReactElement;
 type BillPayerContactCardProps = SurfaceProps & {
     delivery: BillLifecycleDelivery;
@@ -832,13 +844,19 @@ type UseBillLifecycleResult = {
 declare function useBillLifecycle({ billId: providedBillId, sessionEndpoint, getSession, apiBaseUrl, refreshInterval, enabled, fetch: fetchOverride, }: UseBillLifecycleOptions): UseBillLifecycleResult;
 type ConnectedBillLifecycleProps = UseBillLifecycleOptions & {
     appearance?: MindBillReactAppearance;
+    /**
+     * Exposes payer-response simulation controls for an explicit sandbox
+     * playground. Sandbox responses remain indistinguishable from live
+     * lifecycle responses to ordinary host applications.
+     */
+    sandboxControls?: boolean;
     className?: string;
     style?: CSSProperties;
     loadingFallback?: ReactNode;
     errorFallback?: (error: Error, retry: () => Promise<void>) => ReactNode;
     onChanged?: (data: BillLifecycleData) => void;
 };
-declare function ConnectedBillLifecycle({ appearance, className, style, loadingFallback, errorFallback, onChanged, ...options }: ConnectedBillLifecycleProps): ReactElement;
+declare function ConnectedBillLifecycle({ appearance, sandboxControls, className, style, loadingFallback, errorFallback, onChanged, ...options }: ConnectedBillLifecycleProps): ReactElement;
 
 type MindBillWidgetProps = {
     sessionToken: string;
@@ -852,4 +870,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 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 };
+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, BillExplanationOfReview, type BillExplanationOfReviewProps, 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 };