@pfm-platform/budgets-ui-mui 0.1.1 → 0.2.1

package/dist/index.d.cts

@@ -1,12 +1,12 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Budget } from '@pfm-platform/shared';
+import { BudgetWithRelations } from '@pfm-platform/shared';
 
 interface BudgetListProps {
     userId: string;
-    /** Date range start */
-    start_date?: string;
-    /** Date range end */
-    end_date?: string;
+    /** Budget month (1-12) */
+    month?: number;
+    /** Budget year */
+    year?: number;
     /** Custom title for the list */
     title?: string;
     /** Currency symbol to display */
@@ -18,14 +18,14 @@ interface BudgetListProps {
  * BudgetList component displays budgets with progress bars.
  * Shows budget name, amounts, and visual progress indicator.
  */
-declare function BudgetList({ userId, start_date, end_date, title, currencySymbol, maxItems, }: BudgetListProps): react_jsx_runtime.JSX.Element;
+declare function BudgetList({ userId, month, year, title, currencySymbol, maxItems, }: BudgetListProps): react_jsx_runtime.JSX.Element;
 
 interface BudgetSummaryProps {
     userId: string;
-    /** Date range start */
-    start_date?: string;
-    /** Date range end */
-    end_date?: string;
+    /** Budget month (1-12) */
+    month?: number;
+    /** Budget year */
+    year?: number;
     /** Custom title for the summary */
     title?: string;
     /** Currency symbol to display */
@@ -35,7 +35,7 @@ interface BudgetSummaryProps {
  * BudgetSummary component displays aggregate budget statistics.
  * Shows total budgets, budget amount, spent, remaining, and overall state.
  */
-declare function BudgetSummary({ userId, start_date, end_date, title, currencySymbol, }: BudgetSummaryProps): react_jsx_runtime.JSX.Element;
+declare function BudgetSummary({ userId, month, year, title, currencySymbol, }: BudgetSummaryProps): react_jsx_runtime.JSX.Element;
 
 interface BudgetCreateFormProps {
     userId: string;
@@ -45,7 +45,7 @@ declare function BudgetCreateForm({ userId, onSuccess, }: BudgetCreateFormProps)
 
 interface BudgetEditFormProps {
     userId: string;
-    budget: Budget;
+    budget: BudgetWithRelations;
     open: boolean;
     onClose: () => void;
 }
@@ -53,13 +53,13 @@ declare function BudgetEditForm({ userId, budget, open, onClose, }: BudgetEditFo
 
 interface BudgetDeleteButtonProps {
     userId: string;
-    budgetId: number;
+    budgetId: string;
     budgetName: string;
 }
 declare function BudgetDeleteButton({ userId, budgetId, budgetName, }: BudgetDeleteButtonProps): react_jsx_runtime.JSX.Element;
 
 interface BudgetProgressCardProps {
-    budget: Budget;
+    budget: BudgetWithRelations;
     /** Current spent amount */
     currentSpent: number;
     /** Currency symbol to display */
@@ -92,11 +92,11 @@ interface BudgetProgressCardProps {
 declare function BudgetProgressCard({ budget, currentSpent, currencySymbol, showTrend, lastPeriodSpent, }: BudgetProgressCardProps): react_jsx_runtime.JSX.Element;
 
 interface BudgetProgressListProps {
-    budgets: Budget[];
+    budgets: BudgetWithRelations[];
     /** Map of budget ID to current spent amount */
-    spentByBudget: Map<number, number>;
+    spentByBudget: Map<string, number>;
     /** Map of budget ID to last period spent amount (optional) */
-    lastPeriodSpentByBudget?: Map<number, number>;
+    lastPeriodSpentByBudget?: Map<string, number>;
     /** Currency symbol to display */
     currencySymbol?: string;
     /** Show trend indicators */
@@ -300,4 +300,379 @@ interface BudgetInsightDialogProps {
  */
 declare function BudgetInsightDialog({ insight, open, onClose, onSave, saving, currencyFormatter, }: BudgetInsightDialogProps): react_jsx_runtime.JSX.Element | null;
 
-export { BudgetCreateForm, type BudgetCreateFormProps, BudgetDeleteButton, type BudgetDeleteButtonProps, BudgetEditForm, type BudgetEditFormProps, type BudgetInsight, BudgetInsightDialog, type BudgetInsightDialogProps, BudgetInsightsCard, type BudgetInsightsCardProps, BudgetList, type BudgetListProps, type BudgetOverallSummary, BudgetProgressCard, type BudgetProgressCardProps, BudgetProgressList, type BudgetProgressListProps, BudgetSummary, type BudgetSummaryProps, type InsightType };
+/**
+ * BudgetStateIndicator
+ *
+ * Visual indicator for budget state (over/under/on-track).
+ * Migrated from legacy Budgets/BudgetState.js with modern React patterns.
+ *
+ * Features:
+ * - Color-coded state indicators
+ * - Icon-based visual communication
+ * - Percentage-based progress display
+ * - Responsive design with configurable sizes
+ * - Accessibility support
+ *
+ * Migration Notes:
+ * - Legacy: Simple functional component with inline styles
+ * - Modern: TypeScript with Material-UI v7 theming
+ * - Added: Comprehensive type safety, accessibility, responsive sizing
+ */
+type BudgetState = 'under' | 'on-track' | 'over' | 'critical';
+interface BudgetStateIndicatorProps {
+    /**
+     * Current budget state
+     */
+    state: BudgetState;
+    /**
+     * Percentage of budget used (0-100+)
+     */
+    percentage: number;
+    /**
+     * Display variant
+     * @default 'chip'
+     */
+    variant?: 'chip' | 'inline' | 'card';
+    /**
+     * Size of the indicator
+     * @default 'medium'
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Show percentage label
+     * @default true
+     */
+    showPercentage?: boolean;
+    /**
+     * Show state label
+     * @default true
+     */
+    showLabel?: boolean;
+    /**
+     * Custom label override
+     */
+    customLabel?: string;
+}
+/**
+ * Budget state indicator component
+ *
+ * Displays visual indicator for budget state with color coding and icons.
+ * Supports multiple display variants and sizes for different contexts.
+ *
+ * @example
+ * ```tsx
+ * // Chip variant (default)
+ * <BudgetStateIndicator state="over" percentage={110} />
+ *
+ * // Inline variant
+ * <BudgetStateIndicator
+ *   state="on-track"
+ *   percentage={75}
+ *   variant="inline"
+ *   size="small"
+ * />
+ *
+ * // Card variant with custom label
+ * <BudgetStateIndicator
+ *   state="critical"
+ *   percentage={150}
+ *   variant="card"
+ *   customLabel="Way Over Budget"
+ * />
+ * ```
+ */
+declare function BudgetStateIndicator({ state, percentage, variant, size, showPercentage, showLabel, customLabel, }: BudgetStateIndicatorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * BudgetTagInsight
+ *
+ * Tag-specific spending pattern insights component.
+ * Migrated from legacy Budgets/TagInsight.js with modern React patterns.
+ *
+ * Features:
+ * - Tag spending analysis
+ * - Budget assignment recommendations
+ * - Trend visualization
+ * - Actionable insights for unbudgeted tags
+ * - Material-UI v7 theming
+ *
+ * Migration Notes:
+ * - Legacy: MobX store-based with complex tag analysis
+ * - Modern: Controlled component with callback props
+ * - Removed: MobX observables, store injection
+ * - Added: TypeScript types, modern hooks, comprehensive insights
+ */
+interface TagSpendingInsight {
+    /**
+     * Unique insight identifier
+     */
+    id: string;
+    /**
+     * Tag name
+     */
+    tagName: string;
+    /**
+     * Average monthly spending on this tag
+     */
+    averageMonthlySpend: number;
+    /**
+     * Number of months analyzed
+     */
+    monthsAnalyzed: number;
+    /**
+     * Number of transactions with this tag
+     */
+    transactionCount: number;
+    /**
+     * Whether tag is currently budgeted
+     */
+    isBudgeted: boolean;
+    /**
+     * Suggested budget amount (if not budgeted)
+     */
+    suggestedBudget?: number;
+    /**
+     * Spending trend: 'increasing' | 'decreasing' | 'stable'
+     */
+    trend: 'increasing' | 'decreasing' | 'stable';
+    /**
+     * Percentage change in spending (positive or negative)
+     */
+    trendPercentage: number;
+    /**
+     * Recommendation message
+     */
+    recommendation: string;
+}
+interface BudgetTagInsightProps {
+    /**
+     * List of tag spending insights
+     */
+    insights: TagSpendingInsight[];
+    /**
+     * Whether insights are loading
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Callback when "Create Budget" is clicked for a tag
+     */
+    onCreateBudget?: (insight: TagSpendingInsight) => void;
+    /**
+     * Callback when "View Details" is clicked
+     */
+    onViewDetails?: (insight: TagSpendingInsight) => void;
+    /**
+     * Callback when insight is dismissed
+     */
+    onDismiss?: (insight: TagSpendingInsight) => void;
+    /**
+     * Currency formatter
+     */
+    currencyFormatter?: (value: number) => string;
+    /**
+     * Maximum insights to show
+     * @default 5
+     */
+    maxVisible?: number;
+}
+/**
+ * Budget tag insight component
+ *
+ * Displays spending insights for unbudgeted or underbudgeted tags.
+ * Recommends budget creation with suggested amounts based on spending patterns.
+ *
+ * @example
+ * ```tsx
+ * <BudgetTagInsight
+ *   insights={tagInsights}
+ *   onCreateBudget={(insight) => createBudgetForTag(insight)}
+ *   onViewDetails={(insight) => showTagDetails(insight)}
+ * />
+ * ```
+ */
+declare function BudgetTagInsight({ insights, loading, onCreateBudget, onViewDetails, onDismiss, currencyFormatter, maxVisible, }: BudgetTagInsightProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * BudgetOverviewMessage
+ *
+ * Summary message component for budget overview.
+ * Migrated from legacy Budgets/OverviewMessage.js with modern React patterns.
+ *
+ * Features:
+ * - Contextual budget status messages
+ * - Multi-budget summary insights
+ * - Actionable recommendations
+ * - Visual state indicators
+ * - Material-UI v7 theming
+ *
+ * Migration Notes:
+ * - Legacy: Simple string-based message component
+ * - Modern: Rich message component with TypeScript and theming
+ * - Added: State-based styling, icons, action buttons
+ */
+type OverviewMessageType = 'success' | 'warning' | 'error' | 'info';
+interface BudgetOverviewData {
+    /**
+     * Total number of budgets
+     */
+    totalBudgets: number;
+    /**
+     * Number of budgets over limit
+     */
+    budgetsOver: number;
+    /**
+     * Number of budgets on track
+     */
+    budgetsOnTrack: number;
+    /**
+     * Number of budgets under limit
+     */
+    budgetsUnder: number;
+    /**
+     * Total amount over all budgets (negative if over, positive if under)
+     */
+    totalOverUnder: number;
+    /**
+     * Number of unbudgeted tags with significant spending
+     */
+    unbudgetedTagsCount?: number;
+}
+interface BudgetOverviewMessageProps {
+    /**
+     * Budget overview data
+     */
+    data: BudgetOverviewData;
+    /**
+     * Callback when primary action clicked
+     */
+    onAction?: () => void;
+    /**
+     * Custom action button label
+     */
+    actionLabel?: string;
+    /**
+     * Currency formatter
+     */
+    currencyFormatter?: (value: number) => string;
+    /**
+     * Hide action button
+     * @default false
+     */
+    hideAction?: boolean;
+}
+/**
+ * Budget overview message component
+ *
+ * Displays contextual summary message based on budget status.
+ * Provides actionable insights and recommendations.
+ *
+ * @example
+ * ```tsx
+ * <BudgetOverviewMessage
+ *   data={{
+ *     totalBudgets: 5,
+ *     budgetsOver: 2,
+ *     budgetsOnTrack: 2,
+ *     budgetsUnder: 1,
+ *     totalOverUnder: -150,
+ *     unbudgetedTagsCount: 3,
+ *   }}
+ *   onAction={() => navigate('/budgets')}
+ * />
+ * ```
+ */
+declare function BudgetOverviewMessage({ data, onAction, actionLabel, currencyFormatter, hideAction, }: BudgetOverviewMessageProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * BudgetStepper
+ *
+ * Multi-step budget creation/editing form.
+ * Migrated from legacy Budgets/Stepper.js with modern React patterns.
+ *
+ * Features:
+ * - Three-step budget creation workflow
+ * - Step 1: Basic info (name, amount)
+ * - Step 2: Tags selection
+ * - Step 3: Review and confirm
+ * - Progress indicator
+ * - Validation at each step
+ * - Material-UI v7 Stepper component
+ *
+ * Migration Notes:
+ * - Legacy: MobX form state with custom stepper logic
+ * - Modern: React state with Material-UI Stepper
+ * - Removed: MobX observables, custom validation
+ * - Added: TypeScript types, modern hooks, comprehensive validation
+ */
+interface BudgetFormData {
+    /**
+     * Budget name
+     */
+    name: string;
+    /**
+     * Budget amount
+     */
+    budgetAmount: number;
+    /**
+     * Selected tag names
+     */
+    tagNames: string[];
+    /**
+     * Show on dashboard
+     * @default true
+     */
+    showOnDashboard?: boolean;
+}
+interface BudgetStepperProps {
+    /**
+     * Initial form data (for editing)
+     */
+    initialData?: Partial<BudgetFormData>;
+    /**
+     * Available tags for selection
+     */
+    availableTags: string[];
+    /**
+     * Callback when form is submitted
+     */
+    onSubmit: (data: BudgetFormData) => Promise<void>;
+    /**
+     * Callback when form is cancelled
+     */
+    onCancel?: () => void;
+    /**
+     * Whether form is in edit mode
+     * @default false
+     */
+    editMode?: boolean;
+    /**
+     * Whether submission is in progress
+     * @default false
+     */
+    submitting?: boolean;
+    /**
+     * Error message to display
+     */
+    error?: string | null;
+}
+/**
+ * Budget stepper component
+ *
+ * Multi-step form for creating or editing budgets with validation.
+ * Guides users through basic info, tag selection, and review steps.
+ *
+ * @example
+ * ```tsx
+ * <BudgetStepper
+ *   availableTags={['Groceries', 'Utilities', 'Entertainment']}
+ *   onSubmit={async (data) => {
+ *     await createBudget(data);
+ *   }}
+ *   onCancel={() => navigate('/budgets')}
+ * />
+ * ```
+ */
+declare function BudgetStepper({ initialData, availableTags, onSubmit, onCancel, editMode, submitting, error, }: BudgetStepperProps): react_jsx_runtime.JSX.Element;
+
+export { BudgetCreateForm, type BudgetCreateFormProps, BudgetDeleteButton, type BudgetDeleteButtonProps, BudgetEditForm, type BudgetEditFormProps, type BudgetFormData, type BudgetInsight, BudgetInsightDialog, type BudgetInsightDialogProps, BudgetInsightsCard, type BudgetInsightsCardProps, BudgetList, type BudgetListProps, type BudgetOverallSummary, type BudgetOverviewData, BudgetOverviewMessage, type BudgetOverviewMessageProps, BudgetProgressCard, type BudgetProgressCardProps, BudgetProgressList, type BudgetProgressListProps, type BudgetState, BudgetStateIndicator, type BudgetStateIndicatorProps, BudgetStepper, type BudgetStepperProps, BudgetSummary, type BudgetSummaryProps, BudgetTagInsight, type BudgetTagInsightProps, type InsightType, type OverviewMessageType, type TagSpendingInsight };