@mindbill/react 0.21.3 → 0.23.0

package/README.md

@@ -8,7 +8,7 @@ npm install @mindbill/react @mindbill/node
 
 ## Connected lifecycle
 
-`ConnectedBillLifecycle` starts after your server atomically creates and 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 appear in the details view when MindBill makes them available.
 
 ```tsx
 import { ConnectedBillLifecycle } from "@mindbill/react";
@@ -132,7 +132,7 @@ Browser callbacks such as `onChanged` are for immediate UI, navigation, optimist
 
 `BillSubmissionForm` owns the complete pre-submission experience: the bill field schema, required-field rules and red asterisks, validation, service-line editing, source-document selection, PDF uploads, and the single Submit action. Its `bill` value is structurally identical to the server SDK's `CreateBillRequest`.
 
-The partner application only loads initial values and sends the component's immutable snapshot to its authenticated server route. Uploaded files stay in the browser until the user submits.
+The partner application only loads initial values and mints a short-lived browser session. Uploaded files stay in the browser until the user submits; the component validates and sends the immutable snapshot and PDF bytes directly to MindBill.
 
 ```tsx
 import { BillSubmissionForm } from "@mindbill/react";
@@ -142,9 +142,7 @@ import { BillSubmissionForm } from "@mindbill/react";
   attachments={bootstrap.attachments}
   getSession={() => fetch("/api/mindbill/session", { method: "POST" }).then(r => r.json())}
   appearance={{ preset: "qme-companion" }}
-  onSubmit={({ bill, sourceAttachmentIds, uploads }) =>
-    submitBill({ bill, sourceAttachmentIds, uploads })
-  }
+  onSubmitted={({ billId }) => saveLocalBillLink(billId)}
 />
 ```
 
@@ -159,14 +157,90 @@ The component includes the interaction model, not just the markup:
 - 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. Every visible source document is included until removed; uploaded PDFs do not require document-type tagging.
 
-Partners supply tenant-specific bootstrap data, one short-lived browser session callback, and the final server submission callback. Required fields, validation, ZIP lookup, ICD-10 and payer directories, service-line behavior, attachments, and submission UX stay inside `@mindbill/react`, so every integration receives the same billing workflow. Optional `diagnosisOptions`, `procedureOptions`, `modifierOptions`, and lookup callbacks extend or replace defaults when a partner has licensed or organization-specific data.
+Partners supply tenant-specific bootstrap data, one short-lived browser session callback, and optionally an `onSubmitted` callback to persist the returned `billId`. Required fields, validation, ZIP lookup, ICD-10 and payer directories, service-line behavior, PDF encoding, wire-format serialization, atomic submission, attachments, and submission UX stay inside `@mindbill/react`, so every integration receives the same billing workflow. Optional `diagnosisOptions`, `procedureOptions`, `modifierOptions`, and lookup callbacks extend or replace defaults when a partner has licensed or organization-specific data.
 
 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.
 
-`BILL_SUBMISSION_REQUIRED_FIELDS` and `validateBillSubmission` expose the same contract for tests and non-visual integrations. The component never creates a draft; its callback fires only when the user submits a locally valid snapshot.
+`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`.
 
+### Compose individual submission sections
+
+`BillSubmissionForm` is also the form-state provider. Put its named children in your own page shell when you want the same MindBill behavior in a partner-specific layout. The sections do not duplicate required-field, directory, fee, attachment, or submission logic.
+
+```tsx
+import {
+  BillSubmissionActions,
+  BillSubmissionAttachmentsSection,
+  BillSubmissionClaimSection,
+  BillSubmissionForm,
+  BillSubmissionHeader,
+  BillSubmissionPatientSection,
+  BillSubmissionProvidersSection,
+  BillSubmissionServiceLinesSection,
+} from "@mindbill/react";
+
+<BillSubmissionForm {...submissionProps}>
+  <BillSubmissionHeader />
+  <BillSubmissionPatientSection />
+  <BillSubmissionClaimSection />
+  <BillSubmissionProvidersSection />
+  <BillSubmissionServiceLinesSection />
+  <BillSubmissionAttachmentsSection />
+  <BillSubmissionActions />
+</BillSubmissionForm>
+```
+
+Omit a section when another step in your product already supplies that information, or reorder sections to match your workflow. `BillSubmissionActions` remains the only submit control and always validates the complete immutable snapshot.
+
+## Billing dashboard, aging, bill list, and reports
+
+The dashboard components accept plain bill summaries, so they work with `@mindbill/node`'s `listBills()` response, a server-rendered loader, or a partner-owned cache. They never require an API key in the browser.
+
+```tsx
+import {
+  BillingDashboard,
+  BillingReport,
+  buildBillingReportCsv,
+  type BillingDashboardBill,
+} from "@mindbill/react";
+
+const bills: BillingDashboardBill[] = apiBills.map((bill) => ({
+  id: bill.id,
+  billNumber: bill.billNumber,
+  patientName: `${bill.patient.firstName} ${bill.patient.lastName}`,
+  claimNumber: bill.claim.claimNumber,
+  payerName: bill.claim.claimsAdministrator?.name,
+  state: bill.state,
+  // Supply agingDays from your status/lifecycle response, or submittedAt when
+  // your server-side bill summary includes it.
+  agingDays: agingByBillId[bill.id] ?? 0,
+  totalCharge: bill.amounts.charged,
+  totalPaid: bill.amounts.paid,
+  balanceDue: bill.amounts.balance,
+  href: `/billing/${bill.id}`,
+}));
+
+<BillingDashboard
+  bills={bills}
+  appearance={{ preset: "orange-bright" }}
+  onSelectBill={(bill) => router.push(`/billing/${bill.id}`)}
+/>
+
+<BillingReport bills={bills} groupBy="payer" />
+```
+
+Use the smaller pieces independently when a page already has its own shell:
+
+- `BillAgingSummary` — outstanding balance, open count, collected, total billed, and 0–30 / 31–60 / 61–90 / 91+ buckets;
+- `BillList` — responsive desktop table and mobile cards;
+- `BillingReport` — grouped totals by `status`, `payer`, or `aging`;
+- `summarizeBillingDashboard` and `buildBillingReportRows` — presentation-free aggregates;
+- `buildBillingReportCsv` — the same report rows as downloadable CSV text.
+
+Pass only synthetic data to public examples and tests. In production, load organization-scoped bills on the server and authorize each bill-detail route independently.
+
 Use `BillStatusSummary` only when your application already owns status loading and wants a presentation-only component:
 
 ```tsx

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, BillReviewAttachment as BillReviewAttachment$1, BillLifecycleSessionProvider, BillReviewPayer as BillReviewPayer$1, BillLifecycleAction, BillLifecycleDelivery, BillPaymentRecord, BillRemittanceSummary, BillLifecycleData, BillLifecycleClientOptions, BillLifecycleClient, BillEorDocument } from '@mindbill/browser';
-export { BillActivityRecord, BillEorDocument, BillLifecycleAction, BillLifecycleActionId, BillLifecycleClient, BillLifecycleClientOptions, BillLifecycleData, BillLifecycleDelivery, BillLifecycleSession, BillLifecycleSessionProvider, BillLifecycleSessionRequest, BillPaymentRecord, BillRemittanceSummary, CloseBillInput, PostBillPaymentInput, ReopenBillInput, SubmitSecondReviewInput, createBillLifecycleClient } from '@mindbill/browser';
+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';
+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";
 type MindBillReactAppearance = MindBillAppearance & {
@@ -473,8 +473,14 @@ type BillSubmissionFormValue = {
 type BillSubmissionFormProps = {
     initialBill: BillSubmissionInput;
     attachments?: BillSubmissionSourceAttachment[];
-    onSubmit: (value: BillSubmissionFormValue) => void | Promise<void>;
-    /** Short-lived partner browser session. Enables the built-in canonical payer directory. */
+    /**
+     * Legacy custom submission escape hatch. Connected forms should omit this so
+     * the component owns PDF encoding and the Partner API wire contract.
+     */
+    onSubmit?: (value: BillSubmissionFormValue) => void | Promise<void>;
+    /** Called after the connected component atomically creates and submits the bill. */
+    onSubmitted?: (result: BrowserBillSubmissionResult) => void | Promise<void>;
+    /** Short-lived partner browser session. Enables reference data and direct submission. */
     getSession?: BillLifecycleSessionProvider;
     sessionEndpoint?: string;
     apiBaseUrl?: string;
@@ -492,18 +498,37 @@ type BillSubmissionFormProps = {
     submitLabel?: string;
     heading?: ReactNode;
     description?: ReactNode;
+    /**
+     * Optional composable layout. Use the exported section components as children;
+     * the parent form continues to own validation, directory lookups, uploads, and submission.
+     */
+    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", "serviceLines[].code", "serviceLines[].units"];
 type BillSubmissionValidation = {
     valid: boolean;
     fieldErrors: Record<string, string>;
 };
+declare function prepareBillSubmissionDocuments({ attachments, selectedIds, uploads, fetch: fetchOverride, }: {
+    attachments: BillSubmissionSourceAttachment[];
+    selectedIds: string[];
+    uploads: BillSubmissionUpload[];
+    fetch?: typeof globalThis.fetch;
+}): Promise<BrowserBillSubmissionDocument[]>;
 declare function ensureTrailingBillSubmissionLine(lines: BillSubmissionInput["serviceLines"]): BillSubmissionInput["serviceLines"];
 declare function parseBillSubmissionDate(value: string): string | undefined;
 declare function formatBillSubmissionDate(value: string | null | undefined): string;
 declare function applyBillSubmissionEvaluationModifiers(lines: BillSubmissionInput["serviceLines"], type: BillSubmissionEvaluationType): BillSubmissionInput["serviceLines"];
 declare function validateBillSubmission(bill: BillSubmissionInput): BillSubmissionValidation;
-declare function BillSubmissionForm({ initialBill, attachments, onSubmit, getSession, sessionEndpoint, apiBaseUrl, fetch: fetchOverride, onSearchClaimsAdministrators, diagnosisOptions, onSearchDiagnoses, onLookupPostalCode, procedureOptions, modifierOptions, appearance, className, style, disabled, submitLabel, heading, description, }: BillSubmissionFormProps): ReactElement;
+type BillSubmissionSectionId = "header" | "patient" | "claim" | "providers" | "serviceLines" | "attachments" | "actions";
+declare function BillSubmissionHeader(): ReactElement;
+declare function BillSubmissionPatientSection(): ReactElement;
+declare function BillSubmissionClaimSection(): ReactElement;
+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, 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[];
@@ -517,6 +542,86 @@ declare function calculateBillSubmissionAllowedAmount(line: {
     units?: number;
 }, procedures?: BillSubmissionProcedureOption[]): number | undefined;
 
+type BillingDashboardBill = {
+    id: string;
+    billNumber?: string | number;
+    externalId?: string;
+    patientName: string;
+    claimNumber?: string;
+    payerName?: string;
+    state: string;
+    submittedAt?: string;
+    updatedAt?: string;
+    agingDays?: number;
+    totalCharge: number;
+    totalPaid: number;
+    balanceDue: number;
+    href?: string;
+    workItemLabel?: string;
+};
+type BillAgingBucketId = "current" | "31-60" | "61-90" | "91+";
+type BillAgingBucket = {
+    id: BillAgingBucketId;
+    label: string;
+    count: number;
+    balance: number;
+};
+type BillingDashboardSummary = {
+    totalBilled: number;
+    totalPaid: number;
+    outstanding: number;
+    openCount: number;
+    bills: number;
+    aging: BillAgingBucket[];
+};
+type BillingComponentProps = {
+    appearance?: MindBillReactAppearance;
+    className?: string;
+    style?: CSSProperties;
+};
+type BillListProps = BillingComponentProps & {
+    bills: BillingDashboardBill[];
+    onSelectBill?: (bill: BillingDashboardBill) => void;
+    emptyState?: ReactNode;
+};
+type BillAgingSummaryProps = BillingComponentProps & {
+    bills: BillingDashboardBill[];
+    heading?: ReactNode;
+};
+type BillingDashboardProps = BillingComponentProps & {
+    bills: BillingDashboardBill[];
+    heading?: ReactNode;
+    description?: ReactNode;
+    onSelectBill?: (bill: BillingDashboardBill) => void;
+    initialSearch?: string;
+    initialState?: string;
+    hideFilters?: boolean;
+};
+type BillingReportDimension = "status" | "payer" | "aging";
+type BillingReportRow = {
+    key: string;
+    label: string;
+    billCount: number;
+    totalBilled: number;
+    totalPaid: number;
+    balanceDue: number;
+};
+type BillingReportProps = BillingComponentProps & {
+    bills: BillingDashboardBill[];
+    groupBy?: BillingReportDimension;
+    heading?: ReactNode;
+    description?: ReactNode;
+};
+declare function billAgingDays(bill: BillingDashboardBill, now?: Date): number;
+declare function billAgingBucket(bill: BillingDashboardBill, now?: Date): BillAgingBucketId;
+declare function summarizeBillingDashboard(bills: BillingDashboardBill[], now?: Date): BillingDashboardSummary;
+declare function BillList(props: BillListProps): ReactElement;
+declare function BillAgingSummary(props: BillAgingSummaryProps): ReactElement;
+declare function BillingDashboard({ bills, heading, description, onSelectBill, initialSearch, initialState, hideFilters, appearance, className, style }: BillingDashboardProps): ReactElement;
+declare function buildBillingReportRows(bills: BillingDashboardBill[], groupBy?: BillingReportDimension): BillingReportRow[];
+declare function buildBillingReportCsv(bills: BillingDashboardBill[], groupBy?: BillingReportDimension): string;
+declare function BillingReport({ bills, groupBy, heading, description, appearance, className, style }: BillingReportProps): ReactElement;
+
 type BillStatusData = {
     billId: string;
     state: string;
@@ -685,4 +790,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_REQUIRED_FIELDS, type BillActivityEvent, BillActivityTimeline, type BillActivityTimelineProps, BillLifecycleActions, type BillLifecycleActionsProps, BillLifecycleProgress, type BillLifecycleProgressProps, type BillLifecycleStage, 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, type BillSubmissionAddress, type BillSubmissionDiagnosisOption, type BillSubmissionDocumentType, type BillSubmissionEvaluationType, BillSubmissionForm, type BillSubmissionFormProps, type BillSubmissionFormValue, type BillSubmissionInput, type BillSubmissionModifierOption, type BillSubmissionPostalPlace, type BillSubmissionProcedureOption, type BillSubmissionRoute, type BillSubmissionSourceAttachment, type BillSubmissionUpload, type BillSubmissionValidation, ConnectedBillLifecycle, type ConnectedBillLifecycleProps, ConnectedBillStatus, type ConnectedBillStatusProps, DEFAULT_BILL_SUBMISSION_MODIFIERS, DEFAULT_BILL_SUBMISSION_PROCEDURES, MindBillBillReview, MindBillBillTimeline, type MindBillReactAppearance, type MindBillThemePreset, type MindBillWidgetProps, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, applyBillSubmissionEvaluationModifiers, billActivityEventLabel, billLifecycleDisplayLabel, billLifecycleStage, buildBillReviewSaveInput, calculateBillSubmissionAllowedAmount, createBillStatusClient, ensureTrailingBillSubmissionLine, ensureTrailingProcedureLine, formatBillSubmissionDate, mindBillAppearanceStyle, mindBillThemePresets, parseBillSubmissionDate, resolveMindBillAppearance, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };
+export { BILL_SUBMISSION_DIAGNOSIS_QUICK_PICKS, BILL_SUBMISSION_DOCUMENT_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, 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 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, MindBillBillReview, MindBillBillTimeline, type MindBillReactAppearance, type MindBillThemePreset, type MindBillWidgetProps, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, applyBillSubmissionEvaluationModifiers, billActivityEventLabel, billAgingBucket, billAgingDays, billLifecycleDisplayLabel, billLifecycleStage, buildBillReviewSaveInput, buildBillingReportCsv, buildBillingReportRows, calculateBillSubmissionAllowedAmount, createBillStatusClient, ensureTrailingBillSubmissionLine, ensureTrailingProcedureLine, formatBillSubmissionDate, mindBillAppearanceStyle, mindBillThemePresets, parseBillSubmissionDate, prepareBillSubmissionDocuments, resolveMindBillAppearance, summarizeBillingDashboard, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };