@mindbill/react 0.28.2 → 0.30.0

package/README.md

@@ -241,8 +241,19 @@ 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.
+- `BillStatusAgingMatrix` — the management view billers expect: one row per lifecycle status, one column per aging bucket, clickable counts with outstanding balances, and row/column totals;
+- `summarizeBillingDashboard`, `buildBillingReportRows`, and `buildBillStatusAgingMatrix` — presentation-free aggregates;
+- `buildBillingReportCsv` and `buildBillStatusAgingCsv` — the same rows as downloadable CSV text.
+
+```tsx
+<BillStatusAgingMatrix
+  bills={bills}
+  appearance={{ preset: "clinical-blue" }}
+  onSelectCell={(cell) => showDrillDown(cell.state, cell.bucket, cell.bills)}
+/>
+```
+
+Each cell carries the exact bills behind its count, so a drill-down never needs a second query. Pass `stateOrder` to pin your own lifecycle ordering; unknown states append alphabetically.
 
 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.
 
@@ -266,3 +277,19 @@ Use `BillStatusSummary` only when your application already owns status loading a
 `MindBillBillReview` and `MindBillBillTimeline` are available when a hosted flow is a better fit. Native and hosted UI paths use the same bill ID.
 
 Never send a Partner API key or long-lived credential to React/browser code.
+
+## Organization onboarding and billing settings
+
+`OrganizationOnboarding` captures the practice identity, billing provider, locations, and W-9 once — saved straight to your MindBill organization through the browser session — so your users never visit the MindBill dashboard. `BillingSettings` is the compact edit-after-setup variant of the same surface.
+
+```tsx
+import { OrganizationOnboarding } from "@mindbill/react";
+
+<OrganizationOnboarding
+  sessionEndpoint="/api/mindbill/session"
+  appearance={{ preset: "clinical-blue" }}
+  onCompleted={() => enableBillingFeatures()}
+/>
+```
+
+The session must be minted with the optional `organization:manage` permission. Each step saves independently through idempotent upserts that never delete records created elsewhere; the review step mirrors MindBill's onboarding checklist and `onCompleted` fires when everything required is in place.

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, BillLifecycleDelivery, BillReviewAttachment as BillReviewAttachment$1, BrowserBillSubmissionResult, BillLifecycleSessionProvider, BillReviewPayer as BillReviewPayer$1, BrowserBillSubmissionDocument, BillRemittanceSummary, BillEorDocument, BillPaymentRecord, BillLifecycleAction, BillLifecycleData, BillLifecycleClientOptions, BillLifecycleClient } from '@mindbill/browser';
+import { BillReviewData as BillReviewData$1, BillLifecycleDelivery, BillReviewAttachment as BillReviewAttachment$1, BrowserBillSubmissionResult, BillLifecycleSessionProvider, BillReviewPayer as BillReviewPayer$1, BrowserBillSubmissionDocument, OrganizationProfileData, 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" | "midnight-cyan";
@@ -702,6 +702,64 @@ declare function buildBillingReportRows(bills: BillingDashboardBill[], groupBy?:
 declare function buildBillingReportCsv(bills: BillingDashboardBill[], groupBy?: BillingReportDimension): string;
 declare function BillingReport({ bills, groupBy, heading, description, appearance, className, style }: BillingReportProps): ReactElement;
 
+type BillStatusAgingCell = {
+    state: string;
+    bucket: BillAgingBucketId | "total";
+    count: number;
+    balance: number;
+    bills: BillingDashboardBill[];
+};
+type BillStatusAgingRow = {
+    state: string;
+    label: string;
+    cells: BillStatusAgingCell[];
+    total: BillStatusAgingCell;
+};
+type BillStatusAgingMatrixData = {
+    rows: BillStatusAgingRow[];
+    columnTotals: BillStatusAgingCell[];
+    grandTotal: BillStatusAgingCell;
+};
+type BillStatusAgingMatrixProps = {
+    appearance?: MindBillReactAppearance;
+    className?: string;
+    style?: CSSProperties;
+    bills: BillingDashboardBill[];
+    heading?: ReactNode;
+    description?: ReactNode;
+    /** Lifecycle-first row order; unknown states append alphabetically. */
+    stateOrder?: string[];
+    /** Show outstanding balance under each count. Default true. */
+    showBalances?: boolean;
+    onSelectCell?: (cell: BillStatusAgingCell) => void;
+};
+declare const BILL_STATUS_AGING_BUCKETS: {
+    id: BillAgingBucketId;
+    label: string;
+}[];
+declare function buildBillStatusAgingMatrix(bills: BillingDashboardBill[], stateOrder?: string[], now?: Date): BillStatusAgingMatrixData;
+declare function buildBillStatusAgingCsv(bills: BillingDashboardBill[], stateOrder?: string[]): string;
+declare function BillStatusAgingMatrix({ bills, heading, description, stateOrder, showBalances, onSelectCell, appearance, className, style, }: BillStatusAgingMatrixProps): ReactElement;
+
+type OrganizationOnboardingProps = {
+    appearance?: MindBillReactAppearance;
+    className?: string;
+    style?: CSSProperties;
+    sessionEndpoint?: string;
+    getSession?: BillLifecycleSessionProvider;
+    apiBaseUrl?: string;
+    heading?: ReactNode;
+    description?: ReactNode;
+    /** "onboarding" renders a stepper; "settings" stacks every section for editing. */
+    variant?: "onboarding" | "settings";
+    onSaved?: (profile: OrganizationProfileData) => void;
+    onCompleted?: (profile: OrganizationProfileData) => void;
+    onError?: (error: Error) => void;
+};
+declare function OrganizationOnboarding({ appearance, className, style, sessionEndpoint, getSession, apiBaseUrl, heading, description, variant, onSaved, onCompleted, onError, }: OrganizationOnboardingProps): ReactElement;
+/** Compact edit-after-setup variant of {@link OrganizationOnboarding}. */
+declare function BillingSettings(props: Omit<OrganizationOnboardingProps, "variant">): ReactElement;
+
 type BillStatusData = {
     billId: string;
     state: string;
@@ -887,4 +945,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, 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 };
+export { BILL_STATUS_AGING_BUCKETS, 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 BillStatusAgingCell, BillStatusAgingMatrix, type BillStatusAgingMatrixData, type BillStatusAgingMatrixProps, type BillStatusAgingRow, 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, BillingSettings, 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, OrganizationOnboarding, type OrganizationOnboardingProps, PSYCH_QME_DEFAULT_DIAGNOSIS, type UseBillLifecycleOptions, type UseBillLifecycleResult, type UseBillStatusOptions, type UseBillStatusResult, applyBillSubmissionEvaluationDiagnoses, applyBillSubmissionEvaluationModifiers, billActivityEventLabel, billAgingBucket, billAgingDays, billLifecycleDisplayLabel, billLifecycleStage, buildBillReviewSaveInput, buildBillStatusAgingCsv, buildBillStatusAgingMatrix, buildBillingReportCsv, buildBillingReportRows, calculateBillSubmissionAllowedAmount, claimsAdministratorRecommendations, createBillStatusClient, ensureTrailingBillSubmissionLine, ensureTrailingProcedureLine, exactClaimsAdministratorMatch, formatBillSubmissionDate, mindBillAppearanceStyle, mindBillThemePresets, normalizeClaimsAdministratorName, parseBillSubmissionDate, prepareBillSubmissionDocuments, resolveMindBillAppearance, summarizeBillingDashboard, useBillLifecycle, useBillStatus, validateBillSubmission, visibleBillLifecycleActions };