@mindbill/react 0.21.3 → 0.22.0

package/README.md

@@ -167,6 +167,82 @@ Validation is component-owned as well. A missing routing payer is highlighted im
 
 `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

@@ -492,6 +492,11 @@ 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 = {
@@ -503,7 +508,15 @@ 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, 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 +530,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 +778,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, resolveMindBillAppearance, summarizeBillingDashboard, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };