From 1af288aa627ee9a33ea4d04cdeb380e6189fdaa4 Mon Sep 17 00:00:00 2001 From: Casey Wittrock Date: Wed, 12 Nov 2025 15:13:49 -0600 Subject: [PATCH] add notifiaction handling, error handling --- custom_ui/api/db/clients.py | 435 ++++++----- custom_ui/api/db/customers.py | 34 + custom_ui/commands.py | 1 + custom_ui/db_utils.py | 15 +- .../documentation/INTEGRATED_ERROR_STORE.md | 131 ++++ frontend/documentation/SIMPLE_API_TOAST.md | 296 ++++++++ .../components/NotificationDisplay.md | 357 +++++++++ frontend/documentation/stores/errors.md | 699 ++++++++++++++++++ .../documentation/stores/notifications.md | 609 +++++++++++++++ frontend/src/App.vue | 17 + frontend/src/api-enhanced.js | 265 +++++++ frontend/src/api-toast.js | 241 ++++++ frontend/src/api.js | 19 +- frontend/src/components/SideBar.vue | 37 +- .../components/common/NotificationDisplay.vue | 438 +++++++++++ frontend/src/components/pages/Client.vue | 28 +- .../components/pages/ErrorHandlingDemo.vue | 664 +++++++++++++++++ frontend/src/router.js | 3 + frontend/src/stores/errors.js | 341 +++++++++ frontend/src/stores/notifications-primevue.js | 186 +++++ frontend/src/stores/notifications.js | 272 +++++++ 21 files changed, 4864 insertions(+), 224 deletions(-) create mode 100644 custom_ui/api/db/customers.py create mode 100644 frontend/documentation/INTEGRATED_ERROR_STORE.md create mode 100644 frontend/documentation/SIMPLE_API_TOAST.md create mode 100644 frontend/documentation/components/NotificationDisplay.md create mode 100644 frontend/documentation/stores/errors.md create mode 100644 frontend/documentation/stores/notifications.md create mode 100644 frontend/src/api-enhanced.js create mode 100644 frontend/src/api-toast.js create mode 100644 frontend/src/components/common/NotificationDisplay.vue create mode 100644 frontend/src/components/pages/ErrorHandlingDemo.vue create mode 100644 frontend/src/stores/errors.js create mode 100644 frontend/src/stores/notifications-primevue.js create mode 100644 frontend/src/stores/notifications.js diff --git a/custom_ui/api/db/clients.py b/custom_ui/api/db/clients.py index 59281a9..80bcf00 100644 --- a/custom_ui/api/db/clients.py +++ b/custom_ui/api/db/clients.py @@ -1,5 +1,5 @@ import frappe, json -from custom_ui.db_utils import process_query_conditions, build_datatable_response, get_count_or_filters +from custom_ui.db_utils import build_error_response, process_query_conditions, build_datatable_dict, get_count_or_filters, build_success_response # =============================================================================== # CLIENT MANAGEMENT API METHODS @@ -9,222 +9,257 @@ from custom_ui.db_utils import process_query_conditions, build_datatable_respons def get_client_status_counts(weekly=False, week_start_date=None, week_end_date=None): """Get counts of clients by status categories with optional weekly filtering.""" # Build base filters for date range if weekly filtering is enabled - base_filters = {} - if weekly and week_start_date and week_end_date: - # Assuming you have a date field to filter by - adjust the field name as needed - # Common options: creation, modified, custom_date_field, etc. - base_filters["creation"] = ["between", [week_start_date, week_end_date]] + try: + base_filters = {} + if weekly and week_start_date and week_end_date: + # Assuming you have a date field to filter by - adjust the field name as needed + # Common options: creation, modified, custom_date_field, etc. + base_filters["creation"] = ["between", [week_start_date, week_end_date]] - # Helper function to merge base filters with status filters - def get_filters(status_field, status_value): - filters = {status_field: status_value} - filters.update(base_filters) - return filters + # Helper function to merge base filters with status filters + def get_filters(status_field, status_value): + filters = {status_field: status_value} + filters.update(base_filters) + return filters - onsite_meeting_scheduled_status_counts = { - "label": "On-Site Meeting Scheduled", - "not_started": frappe.db.count("Address", filters=get_filters("custom_onsite_meeting_scheduled", "Not Started")), - "in_progress": frappe.db.count("Address", filters=get_filters("custom_onsite_meeting_scheduled", "In Progress")), - "completed": frappe.db.count("Address", filters=get_filters("custom_onsite_meeting_scheduled", "Completed")) - } - - estimate_sent_status_counts = { - "label": "Estimate Sent", - "not_started": frappe.db.count("Address", filters=get_filters("custom_estimate_sent_status", "Not Started")), - "in_progress": frappe.db.count("Address", filters=get_filters("custom_estimate_sent_status", "In Progress")), - "completed": frappe.db.count("Address", filters=get_filters("custom_estimate_sent_status", "Completed")) - } - - job_status_counts = { - "label": "Job Status", - "not_started": frappe.db.count("Address", filters=get_filters("custom_job_status", "Not Started")), - "in_progress": frappe.db.count("Address", filters=get_filters("custom_job_status", "In Progress")), - "completed": frappe.db.count("Address", filters=get_filters("custom_job_status", "Completed")) - } - - payment_received_status_counts = { - "label": "Payment Received", - "not_started": frappe.db.count("Address", filters=get_filters("custom_payment_received_status", "Not Started")), - "in_progress": frappe.db.count("Address", filters=get_filters("custom_payment_received_status", "In Progress")), - "completed": frappe.db.count("Address", filters=get_filters("custom_payment_received_status", "Completed")) - } - - status_dicts = [ - onsite_meeting_scheduled_status_counts, - estimate_sent_status_counts, - job_status_counts, - payment_received_status_counts - ] - - categories = [] - for status_dict in status_dicts: - category = { - "label": status_dict["label"], - "statuses": [ - { - "color": "red", - "label": "Not Started", - "count": status_dict["not_started"] - }, - { - "color": "yellow", - "label": "In Progress", - "count": status_dict["in_progress"] - }, - { - "color": "green", - "label": "Completed", - "count": status_dict["completed"] - } - ] + onsite_meeting_scheduled_status_counts = { + "label": "On-Site Meeting Scheduled", + "not_started": frappe.db.count("Address", filters=get_filters("custom_onsite_meeting_scheduled", "Not Started")), + "in_progress": frappe.db.count("Address", filters=get_filters("custom_onsite_meeting_scheduled", "In Progress")), + "completed": frappe.db.count("Address", filters=get_filters("custom_onsite_meeting_scheduled", "Completed")) } - categories.append(category) - return categories + estimate_sent_status_counts = { + "label": "Estimate Sent", + "not_started": frappe.db.count("Address", filters=get_filters("custom_estimate_sent_status", "Not Started")), + "in_progress": frappe.db.count("Address", filters=get_filters("custom_estimate_sent_status", "In Progress")), + "completed": frappe.db.count("Address", filters=get_filters("custom_estimate_sent_status", "Completed")) + } + + job_status_counts = { + "label": "Job Status", + "not_started": frappe.db.count("Address", filters=get_filters("custom_job_status", "Not Started")), + "in_progress": frappe.db.count("Address", filters=get_filters("custom_job_status", "In Progress")), + "completed": frappe.db.count("Address", filters=get_filters("custom_job_status", "Completed")) + } + + payment_received_status_counts = { + "label": "Payment Received", + "not_started": frappe.db.count("Address", filters=get_filters("custom_payment_received_status", "Not Started")), + "in_progress": frappe.db.count("Address", filters=get_filters("custom_payment_received_status", "In Progress")), + "completed": frappe.db.count("Address", filters=get_filters("custom_payment_received_status", "Completed")) + } + + status_dicts = [ + onsite_meeting_scheduled_status_counts, + estimate_sent_status_counts, + job_status_counts, + payment_received_status_counts + ] + + categories = [] + for status_dict in status_dicts: + category = { + "label": status_dict["label"], + "statuses": [ + { + "color": "red", + "label": "Not Started", + "count": status_dict["not_started"] + }, + { + "color": "yellow", + "label": "In Progress", + "count": status_dict["in_progress"] + }, + { + "color": "green", + "label": "Completed", + "count": status_dict["completed"] + } + ] + } + categories.append(category) + + return build_success_response(categories) + except frappe.ValidationError as ve: + return build_error_response(str(ve), 400) + except Exception as e: + return build_error_response(str(e), 500) @frappe.whitelist() def get_client(client_name): """Get detailed information for a specific client including address, customer, and projects.""" - address = frappe.get_doc("Address", client_name) - customer_name = address.custom_customer_to_bill if address.custom_customer_to_bill else [link.link_name for link in address.links if link.link_doctype == "Customer"][0] if address.links else None - project_names = frappe.db.get_all("Project", fields=["name"], or_filters=[ - ["custom_installation_address", "=", address.address_title], - ["custom_address", "=", address.address_title] - ], limit_page_length=100) - contacts = [] - onsite_meetings = [] - quotations = [] - sales_orders = [] - projects = [frappe.get_doc("Project", proj["name"]) for proj in project_names] - sales_invoices = [] - payment_entries = [] - jobs = [] - for project in projects: - job = [] - jobs.append(job) - customer = frappe.get_doc("Customer", customer_name) - # get all associated data as needed - return { - "address": address, - "customer": customer, - "contacts": contacts, - "jobs": jobs, - "sales_invoices": sales_invoices, - "payment_entries": payment_entries, - "sales_orders": sales_orders, - "quotations": quotations, - "onsite_meetings": onsite_meetings, - } - - + try: + address = frappe.get_doc("Address", client_name) + customer_name = address.custom_customer_to_bill if address.custom_customer_to_bill else [link.link_name for link in address.links if link.link_doctype == "Customer"][0] if address.links else None + if not customer_name: + raise Exception(f"No customer linked to address {client_name}. Suggested fix: Ensure the address is linked to a customer via the ERPnext UI.") + project_names = frappe.db.get_all("Project", fields=["name"], or_filters=[ + ["custom_installation_address", "=", address.address_title], + ["custom_address", "=", address.address_title] + ], limit_page_length=100) + # contacts = [] # currently not needed as the customer doctype comes with contacts + onsite_meetings = frappe.db.get_all( + "On-Site Meeting", + fields=["*"], + filters={"address": address.address_title} + ) + quotations = frappe.db.get_all( + "Quotation", + fields=["*"], + filters={"custom_installation_address": address.address_title} + ) + sales_orders = [] + projects = [frappe.get_doc("Project", proj["name"]) for proj in project_names] + sales_invoices = [] + payment_entries = frappe.db.get_all( + doctype="Payment Entry", + fields=["*"], + filters={"party": customer_name}) + payment_orders = [] + jobs = [] + for project in projects: + job = [] + jobs.append(job) + customer = frappe.get_doc("Customer", customer_name) + # get all associated data as needed + return build_success_response({ + "address": address, + "customer": customer, + # "contacts": [], # currently not needed as the customer doctype comes with contacts + "jobs": jobs, + "sales_invoices": sales_invoices, + "payment_entries": payment_entries, + "sales_orders": sales_orders, + "quotations": quotations, + "onsite_meetings": onsite_meetings, + }) + except frappe.ValidationError as ve: + return build_error_response(str(ve), 400) + except Exception as e: + return build_error_response(str(e), 500) + @frappe.whitelist() def get_clients_table_data(filters={}, sortings=[], page=1, page_size=10): """Get paginated client table data with filtering and sorting support.""" - print("DEBUG: Raw client table query received:", { - "filters": filters, - "sortings": sortings, - "page": page, - "page_size": page_size - }) - - processed_filters, processed_sortings, is_or, page, page_size = process_query_conditions(filters, sortings, page, page_size) - - # Handle count with proper OR filter support - if is_or: - count = frappe.db.sql(*get_count_or_filters("Address", processed_filters))[0][0] - else: - count = frappe.db.count("Address", filters=processed_filters) - - print("DEBUG: Count of addresses matching filters:", count) - - address_names = frappe.db.get_all( - "Address", - fields=["name"], - filters=processed_filters if not is_or else None, - or_filters=processed_filters if is_or else None, - limit=page_size, - start=(page - 1) * page_size, - order_by=processed_sortings - ) - - addresses = [frappe.get_doc("Address", addr["name"]).as_dict() for addr in address_names] - tableRows = [] - for address in addresses: - tableRow = {} - links = address.links - customer_links = [link for link in links if link.link_doctype == "Customer"] if links else None - customer_name = address.get("custom_customer_to_bill") - if not customer_name and not customer_links: - print("DEBUG: No customer links found and no customer to bill.") - customer_name = "N/A" - elif not customer_name and customer_links: - print("DEBUG: No customer to bill. Customer links found:", customer_links) - customer_name = customer_links[0].link_name - tableRow["id"] = address["name"] - tableRow["customer_name"] = customer_name - tableRow["address"] = ( - f"{address['address_line1']}" - f"{' ' + address['address_line2'] if address['address_line2'] else ''} " - f"{address['city']}, {address['state']} {address['pincode']}" + try: + + print("DEBUG: Raw client table query received:", { + "filters": filters, + "sortings": sortings, + "page": page, + "page_size": page_size + }) + + processed_filters, processed_sortings, is_or, page, page_size = process_query_conditions(filters, sortings, page, page_size) + + # Handle count with proper OR filter support + if is_or: + count = frappe.db.sql(*get_count_or_filters("Address", processed_filters))[0][0] + else: + count = frappe.db.count("Address", filters=processed_filters) + + print("DEBUG: Count of addresses matching filters:", count) + + address_names = frappe.db.get_all( + "Address", + fields=["name"], + filters=processed_filters if not is_or else None, + or_filters=processed_filters if is_or else None, + limit=page_size, + start=(page - 1) * page_size, + order_by=processed_sortings ) - tableRow["appointment_scheduled_status"] = address.custom_onsite_meeting_scheduled - tableRow["estimate_sent_status"] = address.custom_estimate_sent_status - tableRow["job_status"] = address.custom_job_status - tableRow["payment_received_status"] = address.custom_payment_received_status - tableRows.append(tableRow) - return build_datatable_response(data=tableRows, count=count, page=page, page_size=page_size) + + addresses = [frappe.get_doc("Address", addr["name"]).as_dict() for addr in address_names] + tableRows = [] + for address in addresses: + tableRow = {} + links = address.links + customer_links = [link for link in links if link.link_doctype == "Customer"] if links else None + customer_name = address.get("custom_customer_to_bill") + if not customer_name and not customer_links: + print("DEBUG: No customer links found and no customer to bill.") + customer_name = "N/A" + elif not customer_name and customer_links: + print("DEBUG: No customer to bill. Customer links found:", customer_links) + customer_name = customer_links[0].link_name + tableRow["id"] = address["name"] + tableRow["customer_name"] = customer_name + tableRow["address"] = ( + f"{address['address_line1']}" + f"{' ' + address['address_line2'] if address['address_line2'] else ''} " + f"{address['city']}, {address['state']} {address['pincode']}" + ) + tableRow["appointment_scheduled_status"] = address.custom_onsite_meeting_scheduled + tableRow["estimate_sent_status"] = address.custom_estimate_sent_status + tableRow["job_status"] = address.custom_job_status + tableRow["payment_received_status"] = address.custom_payment_received_status + tableRows.append(tableRow) + tableDataDict = build_datatable_dict(data=tableRows, count=count, page=page, page_size=page_size) + return build_success_response(tableDataDict) + except frappe.ValidationError as ve: + return build_error_response(str(ve), 400) + except Exception as e: + return build_error_response(str(e), 500) @frappe.whitelist() def upsert_client(data): """Create or update a client (customer and address).""" - data = json.loads(data) - - # Handle customer creation/update - customer = frappe.db.exists("Customer", {"customer_name": data.get("customer_name")}) - if not customer: - customer_doc = frappe.get_doc({ - "doctype": "Customer", - "customer_name": data.get("customer_name"), - "customer_type": data.get("customer_type") + try: + + data = json.loads(data) + + # Handle customer creation/update + customer = frappe.db.exists("Customer", {"customer_name": data.get("customer_name")}) + if not customer: + customer_doc = frappe.get_doc({ + "doctype": "Customer", + "customer_name": data.get("customer_name"), + "customer_type": data.get("customer_type") + }).insert(ignore_permissions=True) + else: + customer_doc = frappe.get_doc("Customer", customer) + + print("Customer:", customer_doc.as_dict()) + + # Check for existing address + filters = { + "address_title": data.get("address_title"), + } + existing_address = frappe.db.exists("Address", filters) + print("Existing address check:", existing_address) + if existing_address: + frappe.throw(f"Address already exists for customer {data.get('customer_name')}.", frappe.ValidationError) + + # Create address + address_doc = frappe.get_doc({ + "doctype": "Address", + "address_line1": data.get("address_line1"), + "city": data.get("city"), + "state": data.get("state"), + "country": "United States", + "address_title": data.get("address_title"), + "pincode": data.get("pincode"), + "custom_customer_to_bill": customer_doc.name }).insert(ignore_permissions=True) - else: - customer_doc = frappe.get_doc("Customer", customer) - - print("Customer:", customer_doc.as_dict()) - - # Check for existing address - filters = { - "address_title": data.get("address_title"), - } - existing_address = frappe.db.exists("Address", filters) - print("Existing address check:", existing_address) - if existing_address: - frappe.throw(f"Address already exists for customer {data.get('customer_name')}.", frappe.ValidationError) - - # Create address - address_doc = frappe.get_doc({ - "doctype": "Address", - "address_line1": data.get("address_line1"), - "city": data.get("city"), - "state": data.get("state"), - "country": "United States", - "address_title": data.get("address_title"), - "pincode": data.get("pincode"), - "custom_customer_to_bill": customer_doc.name - }).insert(ignore_permissions=True) - - # Link address to customer - link = { - "link_doctype": "Customer", - "link_name": customer_doc.name - } - address_doc.append("links", link) - address_doc.save(ignore_permissions=True) + + # Link address to customer + link = { + "link_doctype": "Customer", + "link_name": customer_doc.name + } + address_doc.append("links", link) + address_doc.save(ignore_permissions=True) - return { - "customer": customer_doc, - "address": address_doc, - "success": True - } \ No newline at end of file + return build_success_response({ + "customer": customer_doc.as_dict(), + "address": address_doc.as_dict() + }) + except frappe.ValidationError as ve: + return build_error_response(str(ve), 400) + except Exception as e: + return build_error_response(str(e), 500) \ No newline at end of file diff --git a/custom_ui/api/db/customers.py b/custom_ui/api/db/customers.py new file mode 100644 index 0000000..7430783 --- /dev/null +++ b/custom_ui/api/db/customers.py @@ -0,0 +1,34 @@ +import frappe +from custom_ui.db_utils import build_success_response, build_error_response +# =============================================================================== +# CUSTOMER API METHODS +# =============================================================================== + +@frappe.whitelist() +def get_customer_details(customer_name): + try: + customer = frappe.get_doc("Customer", customer_name) + return build_success_response(customer) + except frappe.ValidationError as ve: + return build_error_response(str(ve), 400) + except Exception as e: + return build_error_response(str(e), 500) + +@frappe.whitelist() +def get_client_names(type): + """Get a list of client names. Maps to value/label pairs for select fields.""" + try: + customer_names = frappe.db.sql(""" + SELECT + customer_name AS label, + name AS value + FROM + `tabCustomer` + WHERE + customer_type = %s + """, (type,), as_dict=True) + return build_success_response(customer_names) + except Exception as e: + return build_error_response(str(e), 500) + except frappe.ValidationError as ve: + return build_error_response(str(ve), 400) \ No newline at end of file diff --git a/custom_ui/commands.py b/custom_ui/commands.py index 43f5960..16218db 100644 --- a/custom_ui/commands.py +++ b/custom_ui/commands.py @@ -29,6 +29,7 @@ def build_frontend(site): click.echo("\nโœ… Frontend build completed successfully.\n") except subprocess.CalledProcessError as e: click.echo(f"\nโŒ Frontend build failed: {e}\n") + exit(1) else: frappe.log_error(message="No frontend directory found for custom_ui", title="Frontend Build Skipped") click.echo(f"\nโš ๏ธ Frontend directory does not exist. Skipping build. Path was {frontend_path}\n") diff --git a/custom_ui/db_utils.py b/custom_ui/db_utils.py index 80b9dd3..2128284 100644 --- a/custom_ui/db_utils.py +++ b/custom_ui/db_utils.py @@ -89,7 +89,7 @@ def process_query_conditions(filters, sortings, page, page_size): return processed_filters, processed_sortings, is_or_filters, page_int, page_size_int -def build_datatable_response(data, count, page, page_size): +def build_datatable_dict(data, count, page, page_size): return { "pagination": { "total": count, @@ -112,4 +112,17 @@ def get_count_or_filters(doctype, or_filters): where_sql = " OR ".join(where_clauses) sql = f"SELECT COUNT(*) FROM `tab{doctype}` WHERE {where_sql}" return sql, values + +def build_error_response(message, status_code=400): + return { + "status": "error", + "message": message, + "status_code": status_code + } + +def build_success_response(data): + return { + "status": "success", + "data": data + } \ No newline at end of file diff --git a/frontend/documentation/INTEGRATED_ERROR_STORE.md b/frontend/documentation/INTEGRATED_ERROR_STORE.md new file mode 100644 index 0000000..a8d76b0 --- /dev/null +++ b/frontend/documentation/INTEGRATED_ERROR_STORE.md @@ -0,0 +1,131 @@ +# ๐ŸŽ‰ Integrated Error Store with Automatic Notifications + +## What's New + +The error store now automatically creates PrimeVue Toast notifications when errors are set. **No need to import both stores anymore!** + +## โœ… Benefits + +- **Single Import**: Only import `useErrorStore` +- **Automatic Notifications**: Error toasts appear automatically +- **Cleaner Code**: Less boilerplate in components +- **Consistent UI**: All notifications use PrimeVue Toast +- **Better Organization**: All error handling in one place + +## ๐Ÿ“– Usage Examples + +### Before (Old Way) + +```javascript +// Had to import both stores +import { useErrorStore } from "@/stores/errors"; +import { useNotificationStore } from "@/stores/notifications-primevue"; + +const errorStore = useErrorStore(); +const notificationStore = useNotificationStore(); + +// Manual notification creation +errorStore.setGlobalError(new Error("Something failed")); +notificationStore.addError("Something failed"); // Had to do this manually +``` + +### After (New Way) + +```javascript +// Only need one import +import { useErrorStore } from "@/stores/errors"; + +const errorStore = useErrorStore(); + +// Automatic notification - toast appears automatically! +errorStore.setGlobalError(new Error("Something failed")); +``` + +## ๐Ÿ› ๏ธ Available Methods + +### Error Methods (Auto-create toasts) + +```javascript +// Global errors +errorStore.setGlobalError(new Error("System error")); + +// Component-specific errors +errorStore.setComponentError("form", new Error("Validation failed")); + +// API errors +errorStore.setApiError("fetch-users", new Error("Network error")); +``` + +### Convenience Methods (Direct notifications) + +```javascript +// Success messages +errorStore.setSuccess("Operation completed!"); + +// Warnings +errorStore.setWarning("Please check your input"); + +// Info messages +errorStore.setInfo("Loading data..."); +``` + +### Disable Automatic Notifications + +```javascript +// Set errors without showing toasts +errorStore.setGlobalError(new Error("Silent error"), false); +errorStore.setComponentError("form", new Error("Silent error"), false); +``` + +## ๐Ÿ”„ Migration Guide + +### Components Using Both Stores + +**Old Code:** + +```javascript +import { useErrorStore } from "@/stores/errors"; +import { useNotificationStore } from "@/stores/notifications-primevue"; + +const errorStore = useErrorStore(); +const notificationStore = useNotificationStore(); + +// Show error +errorStore.setGlobalError(error); +notificationStore.addError("Failed to save"); +``` + +**New Code:** + +```javascript +import { useErrorStore } from "@/stores/errors"; + +const errorStore = useErrorStore(); + +// Error toast shown automatically! +errorStore.setGlobalError(error); +``` + +### API Wrapper Updates + +The `ApiWithToast` wrapper has been updated to use only the error store. All existing usage remains the same, but now it's even simpler internally. + +## ๐ŸŽฏ What Changed Internally + +1. **Error Store**: Now imports `notifications-primevue` store +2. **Automatic Calls**: Error methods automatically call toast notifications +3. **Formatted Titles**: Component names are nicely formatted (e.g., "demo-component" โ†’ "Demo Component Error") +4. **Convenience Methods**: Added `setSuccess()`, `setWarning()`, `setInfo()` methods +5. **ApiWithToast**: Updated to use only error store +6. **Demo Pages**: Updated to show single-store usage + +## ๐Ÿงช Testing + +Visit `/dev/error-handling-demo` to test: + +- All buttons now work with single error store +- Automatic toast notifications +- Error history still works +- Component errors formatted nicely + +The notifications will appear in the top-right corner using PrimeVue Toast styling! diff --git a/frontend/documentation/SIMPLE_API_TOAST.md b/frontend/documentation/SIMPLE_API_TOAST.md new file mode 100644 index 0000000..dd8bbde --- /dev/null +++ b/frontend/documentation/SIMPLE_API_TOAST.md @@ -0,0 +1,296 @@ +# Simple API Error Handling with PrimeVue Toast + +This guide shows how to implement clean, simple error handling using PrimeVue Toast instead of complex custom notification components. + +## Overview + +The simplified approach provides: + +- **Automatic error toasts** using PrimeVue Toast +- **Loading state management** with component-specific tracking +- **Success notifications** for create/update operations +- **Retry logic** with exponential backoff +- **Clean error storage** for debugging and component-specific error handling + +## Key Files + +### 1. PrimeVue Notification Store + +**File:** `/src/stores/notifications-primevue.js` + +```javascript +import { ref } from "vue"; +import { defineStore } from "pinia"; + +export const useNotificationStore = defineStore( + "notifications-primevue", + () => { + // Toast instance reference + const toastInstance = ref(null); + + // Set the toast instance (called from App.vue) + const setToastInstance = (toast) => { + toastInstance.value = toast; + }; + + // Convenience methods for different toast types + const addSuccess = (message, life = 4000) => { + if (toastInstance.value) { + toastInstance.value.add({ + severity: "success", + summary: "Success", + detail: message, + life, + }); + } + }; + + // ... other methods + }, +); +``` + +### 2. Enhanced API Wrapper + +**File:** `/src/api-toast.js` + +Provides a wrapper around your existing API calls with automatic: + +- Error handling and toast notifications +- Loading state management +- Component-specific error tracking +- Retry logic +- Success messages + +```javascript +// Simple usage - automatic error toasts +try { + const result = await ApiWithToast.getClientStatusCounts(); + // Success - data loaded +} catch (error) { + // Error toast automatically shown +} + +// Create operations with success toasts +await ApiWithToast.createClient(formData); +// Shows: "Client created successfully!" +``` + +## Usage in Components + +### 1. Basic Setup + +In your component: + +```vue + +``` + +### 2. Loading States + +The API wrapper automatically manages loading states: + +```vue + +``` + +### 3. Component-Specific Errors + +Access errors for debugging or custom handling: + +```vue + +``` + +## App.vue Integration + +Ensure your `App.vue` includes the Toast component and connects it to the store: + +```vue + + + +``` + +## API Wrapper Methods + +### Convenience Methods + +Pre-configured methods for common operations: + +```javascript +// Data fetching (no success toast) +await ApiWithToast.getClientStatusCounts(); +await ApiWithToast.getPaginatedClientDetails(pagination, filters, sorting); +await ApiWithToast.getPaginatedJobDetails(pagination, filters, sorting); +await ApiWithToast.getPaginatedWarrantyData(pagination, filters, sorting); + +// Create operations (success toast included) +await ApiWithToast.createClient(clientData); + +// Utility operations (with retry logic) +await ApiWithToast.getCityStateByZip(zipcode); +``` + +### Custom API Calls + +For custom operations: + +```javascript +await ApiWithToast.makeApiCall(() => yourApiFunction(), { + componentName: "myComponent", + showSuccessToast: true, + successMessage: "Operation completed!", + showErrorToast: true, + customErrorMessage: "Custom error message", + retryCount: 3, + retryDelay: 1000, + showLoading: true, + loadingMessage: "Processing...", +}); +``` + +## Configuration Options + +| Option | Type | Default | Description | +| -------------------- | ------- | -------------- | ----------------------------------------------- | +| `componentName` | string | null | Component identifier for error/loading tracking | +| `showErrorToast` | boolean | true | Show error toast on failure | +| `showSuccessToast` | boolean | false | Show success toast on completion | +| `showLoading` | boolean | true | Show loading indicator | +| `loadingMessage` | string | 'Loading...' | Loading message to display | +| `successMessage` | string | null | Success message for toast | +| `customErrorMessage` | string | null | Override error message | +| `retryCount` | number | 0 | Number of retry attempts | +| `retryDelay` | number | 1000 | Delay between retries (ms) | +| `operationKey` | string | auto-generated | Unique identifier for operation | + +## Demo Pages + +### 1. Simple API Demo + +**URL:** `/dev/simple-api-demo` + +Shows practical usage with real API calls: + +- Loading client data +- Creating test clients +- Error handling +- Retry logic + +### 2. PrimeVue Toast Demo + +**URL:** `/dev/toast-demo` + +Demonstrates Toast types and error store integration: + +- Different toast severities +- Error store testing +- API simulation + +## Migration from Custom Notifications + +### Old Approach (Custom NotificationDisplay) + +```vue + + + + +``` + +### New Approach (PrimeVue Toast) + +```vue + + +``` + +## Benefits + +1. **Consistency**: Uses PrimeVue components throughout +2. **Simplicity**: No custom notification components needed +3. **Automatic**: Error handling happens automatically +4. **Flexible**: Easy to customize per operation +5. **Maintainable**: Centralized error handling logic +6. **Type Safety**: Clear API with documented options + +## Testing + +Test the implementation by: + +1. Visit `/dev/simple-api-demo` +2. Try different operations: + - Load Clients (success case) + - Create Test Client (success with toast) + - Test Error (error toast) + - Test Retry (retry logic demonstration) + +The toasts will appear in the top-right corner using PrimeVue's default styling. + +## Next Steps + +1. Replace existing API calls with `ApiWithToast` methods +2. Remove custom notification components +3. Update components to use the simplified error handling +4. Test across all your existing workflows + +This approach provides cleaner, more maintainable error handling while leveraging your existing PrimeVue setup. diff --git a/frontend/documentation/components/NotificationDisplay.md b/frontend/documentation/components/NotificationDisplay.md new file mode 100644 index 0000000..44ca49b --- /dev/null +++ b/frontend/documentation/components/NotificationDisplay.md @@ -0,0 +1,357 @@ +# NotificationDisplay Component + +The `NotificationDisplay` component provides a global notification system for displaying toast-style messages to users. It integrates seamlessly with the notification store to show success, error, warning, and info messages with optional action buttons. + +## Overview + +- **Location**: `src/components/common/NotificationDisplay.vue` +- **Type**: Global Component +- **Dependencies**: `@/stores/notifications` +- **Integration**: Added to `App.vue` for global usage + +## Features + +- โœ… **Multiple notification types** (success, error, warning, info) +- โœ… **Configurable positioning** (6 different positions) +- โœ… **Auto-dismiss with progress bars** +- โœ… **Persistent notifications** +- โœ… **Action buttons** with custom handlers +- โœ… **Smooth animations** (slide-in/out effects) +- โœ… **Responsive design** +- โœ… **Accessibility features** + +## Usage + +### Basic Integration + +The component is automatically included in your application via `App.vue`: + +```vue + +``` + +### Triggering Notifications + +Use the notification store to display notifications: + +```javascript +import { useNotificationStore } from "@/stores/notifications"; + +const notificationStore = useNotificationStore(); + +// Simple success notification +notificationStore.addSuccess("Data saved successfully!"); + +// Error notification +notificationStore.addError("Failed to save data", "Save Error"); + +// Custom notification with options +notificationStore.addNotification({ + type: "warning", + title: "Unsaved Changes", + message: "You have unsaved changes. What would you like to do?", + persistent: true, + actions: [ + { + label: "Save", + variant: "primary", + handler: () => saveData(), + }, + { + label: "Discard", + variant: "danger", + handler: () => discardChanges(), + }, + ], +}); +``` + +## Notification Types + +### Success + +- **Color**: Green (#10b981) +- **Icon**: Check circle +- **Use case**: Successful operations, confirmations + +### Error + +- **Color**: Red (#ef4444) +- **Icon**: Alert circle +- **Default duration**: 6000ms (longer than others) +- **Use case**: Errors, failures, critical issues + +### Warning + +- **Color**: Orange (#f59e0b) +- **Icon**: Alert triangle +- **Use case**: Warnings, potential issues, confirmations needed + +### Info + +- **Color**: Blue (#3b82f6) +- **Icon**: Information circle +- **Use case**: General information, tips, status updates + +## Positioning Options + +The notification container can be positioned in 6 different locations: + +```javascript +// Set position via notification store +notificationStore.setPosition("top-right"); // Default + +// Available positions: +// - 'top-right' +// - 'top-left' +// - 'top-center' +// - 'bottom-right' +// - 'bottom-left' +// - 'bottom-center' +``` + +## Action Buttons + +Notifications can include action buttons for user interaction: + +```javascript +notificationStore.addNotification({ + type: "info", + title: "File Upload", + message: "File uploaded successfully. What would you like to do next?", + actions: [ + { + label: "View File", + variant: "primary", + icon: "mdi mdi-eye", + handler: (notification) => { + // Custom action logic + console.log("Viewing file from notification:", notification); + }, + }, + { + label: "Share", + variant: "secondary", + icon: "mdi mdi-share", + handler: () => shareFile(), + dismissAfter: false, // Don't auto-dismiss after action + }, + ], +}); +``` + +### Action Button Variants + +- **primary**: Blue background +- **danger**: Red background +- **secondary**: Gray background (default) + +## Configuration Options + +### Global Configuration + +```javascript +const notificationStore = useNotificationStore(); + +// Set default duration (milliseconds) +notificationStore.setDefaultDuration(5000); + +// Set maximum number of notifications +notificationStore.setMaxNotifications(3); + +// Set position +notificationStore.setPosition("top-center"); +``` + +### Per-Notification Options + +```javascript +notificationStore.addNotification({ + type: 'success', + title: 'Custom Notification', + message: 'This notification has custom settings', + + // Duration (0 = no auto-dismiss) + duration: 8000, + + // Persistent (won't auto-dismiss regardless of duration) + persistent: false, + + // Custom actions + actions: [...], + + // Additional data for handlers + data: { userId: 123, action: 'update' } +}); +``` + +## Responsive Behavior + +The component automatically adapts to different screen sizes: + +- **Desktop**: Fixed width (320px minimum, 400px maximum) +- **Mobile**: Full width with adjusted padding +- **Positioning**: Center positions become full-width on mobile + +## Animations + +The component includes smooth CSS transitions: + +- **Enter**: Slide in from the appropriate direction +- **Leave**: Slide out in the same direction +- **Duration**: 300ms ease-out/ease-in +- **Progress Bar**: Animated countdown for timed notifications + +## Accessibility Features + +- **Keyboard Navigation**: Buttons are focusable and keyboard accessible +- **Screen Readers**: Proper ARIA labels and semantic HTML +- **Color Contrast**: High contrast colors for readability +- **Focus Management**: Proper focus indicators + +## Styling + +The component uses scoped CSS with CSS custom properties for easy customization: + +```css +/* Custom styling example */ +.notification-container { + /* Override default styles */ + --notification-success-color: #059669; + --notification-error-color: #dc2626; + --notification-warning-color: #d97706; + --notification-info-color: #2563eb; +} +``` + +## Best Practices + +### Do's + +- โœ… Use appropriate notification types for different scenarios +- โœ… Keep messages concise and actionable +- โœ… Use action buttons for common follow-up actions +- โœ… Set appropriate durations (longer for errors, shorter for success) +- โœ… Use persistent notifications for critical actions requiring user input + +### Don'ts + +- โŒ Don't show too many notifications at once (overwhelming) +- โŒ Don't use persistent notifications for simple confirmations +- โŒ Don't make notification messages too long +- โŒ Don't use error notifications for non-critical issues + +## Integration with Error Store + +The NotificationDisplay component works seamlessly with the Error Store: + +```javascript +import { useErrorStore } from "@/stores/errors"; + +const errorStore = useErrorStore(); + +// Errors automatically trigger notifications +await errorStore.withErrorHandling( + "api-call", + async () => { + // Your async operation + }, + { + componentName: "myComponent", + showNotification: true, // Automatically shows error notifications + }, +); +``` + +## Examples + +### Basic Usage Examples + +```javascript +const notificationStore = useNotificationStore(); + +// Simple notifications +notificationStore.addSuccess("Changes saved!"); +notificationStore.addError("Network connection failed"); +notificationStore.addWarning("Unsaved changes detected"); +notificationStore.addInfo("New feature available"); + +// Advanced notification with multiple actions +notificationStore.addNotification({ + type: "warning", + title: "Confirm Deletion", + message: "This action cannot be undone. Are you sure?", + persistent: true, + actions: [ + { + label: "Delete", + variant: "danger", + handler: () => { + performDeletion(); + notificationStore.addSuccess("Item deleted successfully"); + }, + }, + { + label: "Cancel", + variant: "secondary", + }, + ], +}); +``` + +### API Integration Examples + +```javascript +// Show loading notification that updates on completion +const loadingId = + notificationStore.showLoadingNotification("Uploading file..."); + +try { + await uploadFile(); + notificationStore.updateToSuccess(loadingId, "File uploaded successfully!"); +} catch (error) { + notificationStore.updateToError(loadingId, "Upload failed: " + error.message); +} +``` + +## Troubleshooting + +### Common Issues + +1. **Notifications not appearing** + - Ensure NotificationDisplay is included in App.vue + - Check z-index conflicts with other components + - Verify notification store is properly imported + +2. **Notifications appearing in wrong position** + - Check the position setting in the store + - Verify CSS is not being overridden + +3. **Action buttons not working** + - Ensure handler functions are properly defined + - Check for JavaScript errors in handlers + +### Debug Mode + +Enable debug logging in development: + +```javascript +// In your main.js or component +if (process.env.NODE_ENV === "development") { + const notificationStore = useNotificationStore(); + // Watch for notification changes + watch( + () => notificationStore.notifications, + (notifications) => { + console.log("Notifications updated:", notifications); + }, + ); +} +``` diff --git a/frontend/documentation/stores/errors.md b/frontend/documentation/stores/errors.md new file mode 100644 index 0000000..b7c2e1c --- /dev/null +++ b/frontend/documentation/stores/errors.md @@ -0,0 +1,699 @@ +# Errors Store + +The errors store provides comprehensive error handling and management for the entire application. It centralizes error tracking, automatic retry logic, and integration with the notification system to provide users with consistent error feedback. + +## Overview + +- **Location**: `src/stores/errors.js` +- **Type**: Pinia Store +- **Purpose**: Centralized error state management and handling +- **Integration**: Works with notification store for user feedback + +## Installation & Setup + +```javascript +// Import in your component +import { useErrorStore } from "@/stores/errors"; + +// Use in component +const errorStore = useErrorStore(); +``` + +## State Structure + +### Core State Properties + +```javascript +state: { + hasError: false, // Global error flag + lastError: null, // Most recent global error + apiErrors: new Map(), // API-specific errors by key + componentErrors: { // Component-specific errors + dataTable: null, + form: null, + clients: null, + jobs: null, + timesheets: null, + warranties: null, + routes: null + }, + errorHistory: [], // Historical error log + maxHistorySize: 50, // Maximum history entries + autoNotifyErrors: true // Auto-show notifications for errors +} +``` + +### Error Object Structure + +```javascript +{ + message: 'Error description', // Human-readable error message + type: 'api_error', // Error classification + timestamp: '2025-11-12T10:30:00Z', // When error occurred + name: 'ValidationError', // Error name (if available) + stack: 'Error stack trace...', // Stack trace (if available) + status: 404, // HTTP status (for API errors) + statusText: 'Not Found', // HTTP status text + data: {...} // Additional error data +} +``` + +## Getters + +### `hasAnyError` + +Check if there are any errors in the application. + +```javascript +const hasErrors = errorStore.hasAnyError; +``` + +### `getComponentError(componentName)` + +Get error for a specific component. + +```javascript +const formError = errorStore.getComponentError("form"); +``` + +### `getApiError(apiKey)` + +Get error for a specific API operation. + +```javascript +const loginError = errorStore.getApiError("user-login"); +``` + +### `getRecentErrors(limit)` + +Get recent errors from history. + +```javascript +const recentErrors = errorStore.getRecentErrors(10); +``` + +## Actions + +### Global Error Management + +#### `setGlobalError(error, showNotification)` + +Set a global application error. + +```javascript +errorStore.setGlobalError( + new Error("Critical system failure"), + true, // Show notification +); + +// With custom error object +errorStore.setGlobalError({ + message: "Database connection lost", + type: "connection_error", + recoverable: true, +}); +``` + +#### `clearGlobalError()` + +Clear the global error state. + +```javascript +errorStore.clearGlobalError(); +``` + +### Component-Specific Error Management + +#### `setComponentError(componentName, error, showNotification)` + +Set an error for a specific component. + +```javascript +// Set error for form component +errorStore.setComponentError("form", new Error("Validation failed"), true); + +// Clear error (pass null) +errorStore.setComponentError("form", null); +``` + +#### `clearComponentError(componentName)` + +Clear error for a specific component. + +```javascript +errorStore.clearComponentError("form"); +``` + +### API Error Management + +#### `setApiError(apiKey, error, showNotification)` + +Set an error for a specific API operation. + +```javascript +// Set API error +errorStore.setApiError("user-login", apiError, true); + +// Clear API error (pass null) +errorStore.setApiError("user-login", null); +``` + +#### `clearApiError(apiKey)` + +Clear error for a specific API operation. + +```javascript +errorStore.clearApiError("user-login"); +``` + +### Bulk Operations + +#### `clearAllErrors()` + +Clear all errors from the store. + +```javascript +errorStore.clearAllErrors(); +``` + +### Advanced Error Handling + +#### `handleApiCall(apiKey, apiFunction, options)` + +Handle an API call with automatic error management and retry logic. + +```javascript +const result = await errorStore.handleApiCall( + "fetch-users", + async () => { + return await api.getUsers(); + }, + { + showNotification: true, + retryCount: 2, + retryDelay: 1000, + onSuccess: (result) => console.log("Success:", result), + onError: (error) => console.log("Failed:", error), + }, +); +``` + +#### `withErrorHandling(operationKey, asyncOperation, options)` + +Wrap an async operation with comprehensive error handling. + +```javascript +const result = await errorStore.withErrorHandling( + "save-data", + async () => { + return await saveUserData(); + }, + { + componentName: "userForm", + showNotification: true, + rethrow: false, // Don't re-throw errors + }, +); +``` + +## Error Types + +The store automatically categorizes errors into different types: + +### `string_error` + +Simple string errors. + +```javascript +errorStore.setGlobalError("Something went wrong"); +``` + +### `javascript_error` + +Standard JavaScript Error objects. + +```javascript +errorStore.setGlobalError(new Error("Validation failed")); +``` + +### `api_error` + +HTTP/API response errors with status codes. + +```javascript +// Automatically detected from axios-style error objects +{ + message: 'Not Found', + status: 404, + statusText: 'Not Found', + type: 'api_error', + data: {...} +} +``` + +### `network_error` + +Network connectivity errors. + +```javascript +{ + message: 'Network error - please check your connection', + type: 'network_error' +} +``` + +### `unknown_error` + +Unrecognized error formats. + +```javascript +{ + message: 'An unknown error occurred', + type: 'unknown_error', + originalError: {...} +} +``` + +## Configuration Methods + +### `setAutoNotifyErrors(enabled)` + +Enable/disable automatic error notifications. + +```javascript +errorStore.setAutoNotifyErrors(false); // Disable auto-notifications +``` + +### `setMaxHistorySize(size)` + +Set maximum number of errors to keep in history. + +```javascript +errorStore.setMaxHistorySize(100); +``` + +## Usage Patterns + +### Basic Error Handling + +```javascript +const errorStore = useErrorStore(); + +// Simple error setting +try { + await riskyOperation(); +} catch (error) { + errorStore.setGlobalError(error); +} + +// Component-specific error +try { + await validateForm(); +} catch (validationError) { + errorStore.setComponentError("form", validationError); +} +``` + +### API Error Handling with Retry + +```javascript +// Automatic retry logic +const userData = await errorStore.handleApiCall( + "fetch-user-data", + async () => { + const response = await fetch("/api/users"); + if (!response.ok) throw new Error("Failed to fetch users"); + return response.json(); + }, + { + retryCount: 3, + retryDelay: 1000, + showNotification: true, + }, +); +``` + +### Comprehensive Operation Wrapping + +```javascript +// Wrap complex operations +const result = await errorStore.withErrorHandling( + "complex-workflow", + async () => { + // Step 1: Validate data + await validateInputData(); + + // Step 2: Save to database + const saveResult = await saveToDatabase(); + + // Step 3: Send notification email + await sendNotificationEmail(); + + return saveResult; + }, + { + componentName: "workflow", + showNotification: true, + rethrow: false, + }, +); + +if (result) { + // Success - result contains the return value + console.log("Workflow completed:", result); +} else { + // Error occurred - check component error for details + const workflowError = errorStore.getComponentError("workflow"); + console.log("Workflow failed:", workflowError?.message); +} +``` + +### Integration with Vue Components + +```javascript +// In a Vue component +import { useErrorStore } from "@/stores/errors"; +import { useNotificationStore } from "@/stores/notifications"; + +export default { + setup() { + const errorStore = useErrorStore(); + const notificationStore = useNotificationStore(); + + const submitForm = async (formData) => { + // Clear any previous errors + errorStore.clearComponentError("form"); + + try { + await errorStore.withErrorHandling( + "form-submit", + async () => { + const result = await api.submitForm(formData); + notificationStore.addSuccess("Form submitted successfully!"); + return result; + }, + { + componentName: "form", + showNotification: true, + }, + ); + + // Reset form on success + resetForm(); + } catch (error) { + // Error handling is automatic, but you can add custom logic here + console.log("Form submission failed"); + } + }; + + return { + submitForm, + formError: computed(() => errorStore.getComponentError("form")), + }; + }, +}; +``` + +## Integration with Enhanced API + +The errors store works seamlessly with the enhanced API wrapper: + +```javascript +import { ApiWithErrorHandling } from "@/api-enhanced"; + +// The enhanced API automatically uses the error store +try { + const clients = await ApiWithErrorHandling.getPaginatedClientDetails( + pagination, + filters, + [], + { + componentName: "clients", + retryCount: 2, + showErrorNotifications: true, + }, + ); +} catch (error) { + // Error is automatically handled by the error store + // Check component error for details + const clientError = errorStore.getComponentError("clients"); +} +``` + +## Error Recovery Patterns + +### Graceful Degradation + +```javascript +const loadCriticalData = async () => { + let primaryData = null; + let fallbackData = null; + + // Try primary data source + try { + primaryData = await errorStore.withErrorHandling( + "primary-data", + () => api.getPrimaryData(), + { showNotification: false, rethrow: true }, + ); + } catch (error) { + console.log("Primary data failed, trying fallback..."); + + // Try fallback data source + try { + fallbackData = await errorStore.withErrorHandling( + "fallback-data", + () => api.getFallbackData(), + { showNotification: false, rethrow: true }, + ); + + notificationStore.addWarning( + "Using cached data due to connectivity issues", + ); + } catch (fallbackError) { + errorStore.setGlobalError("Unable to load data from any source"); + return null; + } + } + + return primaryData || fallbackData; +}; +``` + +### User-Driven Error Recovery + +```javascript +const handleApiError = async (operation) => { + try { + return await operation(); + } catch (error) { + // Show error with recovery options + notificationStore.addNotification({ + type: "error", + title: "Operation Failed", + message: "Would you like to try again or continue with cached data?", + persistent: true, + actions: [ + { + label: "Retry", + variant: "primary", + handler: () => handleApiError(operation), // Recursive retry + }, + { + label: "Use Cached Data", + variant: "secondary", + handler: () => loadCachedData(), + }, + { + label: "Cancel", + variant: "secondary", + }, + ], + }); + + throw error; // Let caller handle as needed + } +}; +``` + +## Debugging & Monitoring + +### Error History Access + +```javascript +// Get all error history for debugging +const allErrors = errorStore.errorHistory; + +// Get recent errors with details +const recent = errorStore.getRecentErrors(5); +recent.forEach((error) => { + console.log(`[${error.timestamp}] ${error.source}: ${error.message}`); +}); + +// Filter errors by type +const apiErrors = errorStore.errorHistory.filter((e) => e.type === "api_error"); +``` + +### Error Reporting + +```javascript +// Send error reports to monitoring service +const reportErrors = () => { + const recentErrors = errorStore.getRecentErrors(10); + + recentErrors.forEach((error) => { + if (error.type === "api_error" && error.status >= 500) { + // Report server errors + analyticsService.reportError({ + message: error.message, + url: window.location.href, + userAgent: navigator.userAgent, + timestamp: error.timestamp, + stack: error.stack, + }); + } + }); +}; +``` + +## Testing + +### Unit Testing + +```javascript +import { setActivePinia, createPinia } from "pinia"; +import { useErrorStore } from "@/stores/errors"; + +describe("Errors Store", () => { + beforeEach(() => { + setActivePinia(createPinia()); + }); + + it("sets and clears global errors", () => { + const store = useErrorStore(); + + store.setGlobalError("Test error"); + expect(store.hasError).toBe(true); + expect(store.lastError.message).toBe("Test error"); + + store.clearGlobalError(); + expect(store.hasError).toBe(false); + }); + + it("handles component errors", () => { + const store = useErrorStore(); + + store.setComponentError("form", new Error("Validation failed")); + expect(store.getComponentError("form").message).toBe("Validation failed"); + + store.clearComponentError("form"); + expect(store.getComponentError("form")).toBeNull(); + }); + + it("tracks error history", () => { + const store = useErrorStore(); + + store.setGlobalError("Error 1"); + store.setGlobalError("Error 2"); + + expect(store.errorHistory).toHaveLength(2); + expect(store.getRecentErrors(1)[0].message).toBe("Error 2"); + }); +}); +``` + +### Integration Testing + +```javascript +// Test error handling with API calls +it("handles API errors correctly", async () => { + const store = useErrorStore(); + const mockApi = jest.fn().mockRejectedValue(new Error("API Error")); + + const result = await store.withErrorHandling("test-api", mockApi, { + componentName: "test", + showNotification: false, + rethrow: false, + }); + + expect(result).toBeNull(); + expect(store.getComponentError("test").message).toBe("API Error"); +}); +``` + +## Best Practices + +### Do's + +- โœ… Use component-specific errors for UI validation +- โœ… Use API-specific errors for network operations +- โœ… Enable auto-notifications for user-facing errors +- โœ… Use retry logic for transient failures +- โœ… Clear errors when operations succeed +- โœ… Keep error messages user-friendly and actionable + +### Don'ts + +- โŒ Don't set global errors for minor validation issues +- โŒ Don't ignore error context (component/API source) +- โŒ Don't let error history grow indefinitely +- โŒ Don't show technical stack traces to end users +- โŒ Don't retry operations that will consistently fail + +### Performance Considerations + +- Error history is automatically trimmed to prevent memory leaks +- Use component-specific errors to isolate issues +- Clear errors promptly when no longer relevant +- Consider disabling auto-notifications for high-frequency operations + +## Common Patterns + +### Form Validation Errors + +```javascript +const validateAndSubmit = async (formData) => { + errorStore.clearComponentError("form"); + + try { + await errorStore.withErrorHandling( + "form-validation", + async () => { + validateFormData(formData); + await submitForm(formData); + }, + { + componentName: "form", + showNotification: true, + }, + ); + } catch (error) { + // Validation errors are now stored in component error + // and automatically displayed to user + } +}; +``` + +### Background Task Monitoring + +```javascript +const monitorBackgroundTask = async (taskId) => { + await errorStore.handleApiCall( + `task-${taskId}`, + async () => { + const status = await api.getTaskStatus(taskId); + + if (status.failed) { + throw new Error(`Task failed: ${status.error}`); + } + + return status; + }, + { + retryCount: 5, + retryDelay: 2000, + showNotification: status.failed, // Only notify on final failure + }, + ); +}; +``` diff --git a/frontend/documentation/stores/notifications.md b/frontend/documentation/stores/notifications.md new file mode 100644 index 0000000..5ce14f0 --- /dev/null +++ b/frontend/documentation/stores/notifications.md @@ -0,0 +1,609 @@ +# Notifications Store + +The notifications store provides centralized state management for application-wide notifications. It handles the creation, management, and lifecycle of toast-style notifications with support for multiple types, positions, and interactive actions. + +## Overview + +- **Location**: `src/stores/notifications.js` +- **Type**: Pinia Store +- **Purpose**: Global notification state management +- **Integration**: Used by NotificationDisplay component + +## Installation & Setup + +```javascript +// Import in your component +import { useNotificationStore } from "@/stores/notifications"; + +// Use in component +const notificationStore = useNotificationStore(); +``` + +## State Structure + +### Core State Properties + +```javascript +state: { + notifications: [], // Array of active notifications + defaultDuration: 4000, // Default auto-dismiss time (ms) + maxNotifications: 5, // Maximum concurrent notifications + position: 'top-right', // Default position + nextId: 1 // Auto-incrementing ID counter +} +``` + +### Notification Object Structure + +```javascript +{ + id: 1, // Unique identifier + type: 'success', // 'success' | 'error' | 'warning' | 'info' + title: 'Operation Complete', // Notification title + message: 'Data saved successfully', // Main message + duration: 4000, // Auto-dismiss time (0 = no auto-dismiss) + persistent: false, // If true, won't auto-dismiss + actions: [], // Array of action buttons + data: null, // Additional data for handlers + timestamp: '2025-11-12T10:30:00Z', // Creation timestamp + dismissed: false, // Whether notification is dismissed + seen: false // Whether user has interacted with it +} +``` + +## Getters + +### `getNotificationsByType(type)` + +Get all notifications of a specific type. + +```javascript +const errorNotifications = notificationStore.getNotificationsByType("error"); +``` + +### `activeNotifications` + +Get all non-dismissed notifications. + +```javascript +const active = notificationStore.activeNotifications; +``` + +### `activeCount` + +Get count of active notifications. + +```javascript +const count = notificationStore.activeCount; +``` + +### `hasErrorNotifications` + +Check if there are any active error notifications. + +```javascript +const hasErrors = notificationStore.hasErrorNotifications; +``` + +### `hasSuccessNotifications` + +Check if there are any active success notifications. + +```javascript +const hasSuccess = notificationStore.hasSuccessNotifications; +``` + +## Actions + +### Core Notification Methods + +#### `addNotification(notification)` + +Add a new notification with full configuration options. + +```javascript +const notificationId = notificationStore.addNotification({ + type: "warning", + title: "Confirm Action", + message: "This will permanently delete the item.", + persistent: true, + actions: [ + { + label: "Delete", + variant: "danger", + handler: () => performDelete(), + }, + { + label: "Cancel", + variant: "secondary", + }, + ], + data: { itemId: 123 }, +}); +``` + +#### Convenience Methods + +```javascript +// Quick success notification +notificationStore.addSuccess("Operation completed!"); +notificationStore.addSuccess("Custom message", "Custom Title", { + duration: 6000, +}); + +// Quick error notification +notificationStore.addError("Something went wrong!"); +notificationStore.addError("Custom error", "Error Title", { persistent: true }); + +// Quick warning notification +notificationStore.addWarning("Please confirm this action"); + +// Quick info notification +notificationStore.addInfo("New feature available"); +``` + +### Notification Management + +#### `dismissNotification(id)` + +Mark a notification as dismissed (hides it but keeps in history). + +```javascript +notificationStore.dismissNotification(notificationId); +``` + +#### `removeNotification(id)` + +Completely remove a notification from the store. + +```javascript +notificationStore.removeNotification(notificationId); +``` + +#### `markAsSeen(id)` + +Mark a notification as seen (user has interacted with it). + +```javascript +notificationStore.markAsSeen(notificationId); +``` + +#### `updateNotification(id, updates)` + +Update an existing notification's properties. + +```javascript +notificationStore.updateNotification(notificationId, { + type: "success", + message: "Updated message", + persistent: false, +}); +``` + +### Bulk Operations + +#### `clearType(type)` + +Remove all notifications of a specific type. + +```javascript +notificationStore.clearType("error"); // Remove all error notifications +``` + +#### `clearAll()` + +Remove all notifications. + +```javascript +notificationStore.clearAll(); +``` + +#### `clearDismissed()` + +Remove all dismissed notifications from history. + +```javascript +notificationStore.clearDismissed(); +``` + +### Loading Notifications + +#### `showLoadingNotification(message, title)` + +Show a persistent loading notification that can be updated later. + +```javascript +const loadingId = notificationStore.showLoadingNotification( + "Uploading file...", + "Please Wait", +); +``` + +#### `updateToSuccess(id, message, title)` + +Update a loading notification to success and auto-dismiss. + +```javascript +notificationStore.updateToSuccess( + loadingId, + "File uploaded successfully!", + "Upload Complete", +); +``` + +#### `updateToError(id, message, title)` + +Update a loading notification to error and auto-dismiss. + +```javascript +notificationStore.updateToError( + loadingId, + "Upload failed. Please try again.", + "Upload Failed", +); +``` + +### API Integration Helpers + +#### `showApiSuccess(operation, customMessage)` + +Show standardized success notifications for API operations. + +```javascript +// Uses default messages based on operation +notificationStore.showApiSuccess("create"); // "Item created successfully" +notificationStore.showApiSuccess("update"); // "Item updated successfully" +notificationStore.showApiSuccess("delete"); // "Item deleted successfully" +notificationStore.showApiSuccess("fetch"); // "Data loaded successfully" + +// With custom message +notificationStore.showApiSuccess("create", "New client added successfully!"); +``` + +#### `showApiError(operation, error, customMessage)` + +Show standardized error notifications for API operations. + +```javascript +// Automatically extracts error message from different error formats +notificationStore.showApiError("create", apiError); +notificationStore.showApiError("update", "Network timeout occurred"); +notificationStore.showApiError("delete", errorObject, "Custom error message"); +``` + +### Configuration Methods + +#### `setPosition(position)` + +Set the global notification position. + +```javascript +// Available positions: +notificationStore.setPosition("top-right"); // Default +notificationStore.setPosition("top-left"); +notificationStore.setPosition("top-center"); +notificationStore.setPosition("bottom-right"); +notificationStore.setPosition("bottom-left"); +notificationStore.setPosition("bottom-center"); +``` + +#### `setDefaultDuration(duration)` + +Set the default auto-dismiss duration (milliseconds). + +```javascript +notificationStore.setDefaultDuration(5000); // 5 seconds +``` + +#### `setMaxNotifications(max)` + +Set maximum number of concurrent notifications. + +```javascript +notificationStore.setMaxNotifications(3); +``` + +### Advanced Workflow Helper + +#### `withNotifications(operation, asyncFunction, options)` + +Wrap an async operation with automatic loading/success/error notifications. + +```javascript +const result = await notificationStore.withNotifications( + "save", + async () => { + return await saveDataToApi(); + }, + { + loadingMessage: "Saving changes...", + successMessage: "Changes saved successfully!", + errorMessage: null, // Use default error handling + showLoading: true, + }, +); +``` + +## Action Button Configuration + +### Action Object Structure + +```javascript +{ + label: 'Button Text', // Required: Button label + variant: 'primary', // Optional: 'primary' | 'danger' | 'secondary' + icon: 'mdi mdi-check', // Optional: Icon class + handler: (notification) => {}, // Optional: Click handler function + dismissAfter: true // Optional: Auto-dismiss after click (default: true) +} +``` + +### Action Examples + +```javascript +notificationStore.addNotification({ + type: "warning", + title: "Unsaved Changes", + message: "You have unsaved changes. What would you like to do?", + persistent: true, + actions: [ + { + label: "Save", + variant: "primary", + icon: "mdi mdi-content-save", + handler: (notification) => { + saveChanges(); + // Access notification data if needed + console.log("Saving from notification:", notification.data); + }, + }, + { + label: "Discard", + variant: "danger", + icon: "mdi mdi-delete", + handler: () => { + discardChanges(); + }, + }, + { + label: "Keep Editing", + variant: "secondary", + dismissAfter: false, // Don't dismiss, let user continue editing + }, + ], +}); +``` + +## Usage Patterns + +### Basic Notifications + +```javascript +const notificationStore = useNotificationStore(); + +// Simple success +notificationStore.addSuccess("Data saved successfully!"); + +// Simple error +notificationStore.addError("Failed to connect to server"); + +// Custom duration +notificationStore.addWarning("Session expires in 5 minutes", "Warning", { + duration: 8000, +}); +``` + +### API Operation Notifications + +```javascript +// Method 1: Manual handling +try { + await apiCall(); + notificationStore.addSuccess("Operation completed successfully!"); +} catch (error) { + notificationStore.addError(error.message, "Operation Failed"); +} + +// Method 2: Using API helpers +try { + await apiCall(); + notificationStore.showApiSuccess("create"); +} catch (error) { + notificationStore.showApiError("create", error); +} + +// Method 3: Using workflow helper +await notificationStore.withNotifications("create", async () => { + return await apiCall(); +}); +``` + +### Loading States + +```javascript +// Show loading notification +const loadingId = notificationStore.showLoadingNotification("Processing..."); + +try { + const result = await longRunningOperation(); + notificationStore.updateToSuccess(loadingId, "Operation completed!"); +} catch (error) { + notificationStore.updateToError(loadingId, "Operation failed"); +} +``` + +### Interactive Notifications + +```javascript +// Confirmation dialog +notificationStore.addNotification({ + type: "warning", + title: "Delete Confirmation", + message: `Are you sure you want to delete "${itemName}"?`, + persistent: true, + actions: [ + { + label: "Yes, Delete", + variant: "danger", + handler: async () => { + const deleteId = + notificationStore.showLoadingNotification("Deleting..."); + try { + await deleteItem(itemId); + notificationStore.updateToSuccess( + deleteId, + "Item deleted successfully", + ); + refreshData(); + } catch (error) { + notificationStore.updateToError(deleteId, "Failed to delete item"); + } + }, + }, + { + label: "Cancel", + variant: "secondary", + }, + ], +}); + +// Multi-step workflow +notificationStore.addNotification({ + type: "info", + title: "Export Complete", + message: "Your data has been exported successfully.", + actions: [ + { + label: "Download", + variant: "primary", + icon: "mdi mdi-download", + handler: () => downloadFile(), + }, + { + label: "Email", + variant: "secondary", + icon: "mdi mdi-email", + handler: () => emailFile(), + }, + { + label: "View", + variant: "secondary", + icon: "mdi mdi-eye", + handler: () => viewFile(), + }, + ], +}); +``` + +## Integration with Vue Components + +### In Composition API + +```javascript +import { useNotificationStore } from "@/stores/notifications"; + +export default { + setup() { + const notificationStore = useNotificationStore(); + + const handleSubmit = async () => { + try { + await submitForm(); + notificationStore.addSuccess("Form submitted successfully!"); + } catch (error) { + notificationStore.addError("Failed to submit form", "Submission Error"); + } + }; + + return { + handleSubmit, + }; + }, +}; +``` + +### In Options API + +```javascript +import { mapActions, mapGetters } from "pinia"; +import { useNotificationStore } from "@/stores/notifications"; + +export default { + computed: { + ...mapGetters(useNotificationStore, [ + "activeCount", + "hasErrorNotifications", + ]), + }, + methods: { + ...mapActions(useNotificationStore, ["addSuccess", "addError", "clearAll"]), + + async saveData() { + try { + await this.apiCall(); + this.addSuccess("Data saved!"); + } catch (error) { + this.addError(error.message); + } + }, + }, +}; +``` + +## Best Practices + +### Do's + +- โœ… Use appropriate notification types for different scenarios +- โœ… Keep messages concise and actionable +- โœ… Use loading notifications for long-running operations +- โœ… Provide clear action buttons for next steps +- โœ… Set appropriate durations (longer for errors, shorter for success) +- โœ… Use persistent notifications for critical actions requiring user input + +### Don'ts + +- โŒ Don't overwhelm users with too many notifications +- โŒ Don't use persistent notifications for simple confirmations +- โŒ Don't make notification messages too long +- โŒ Don't forget to handle loading state cleanup +- โŒ Don't use success notifications for every small action + +### Performance Considerations + +- The store automatically limits concurrent notifications +- Dismissed notifications are kept in history for debugging +- Use `clearDismissed()` periodically to prevent memory leaks +- Action handlers should be lightweight to avoid blocking the UI + +## Testing + +### Unit Testing + +```javascript +import { setActivePinia, createPinia } from "pinia"; +import { useNotificationStore } from "@/stores/notifications"; + +describe("Notifications Store", () => { + beforeEach(() => { + setActivePinia(createPinia()); + }); + + it("adds notifications correctly", () => { + const store = useNotificationStore(); + const id = store.addSuccess("Test message"); + + expect(store.activeNotifications).toHaveLength(1); + expect(store.activeNotifications[0].message).toBe("Test message"); + expect(store.activeNotifications[0].type).toBe("success"); + }); + + it("dismisses notifications", () => { + const store = useNotificationStore(); + const id = store.addInfo("Test"); + + store.dismissNotification(id); + expect(store.activeNotifications).toHaveLength(0); + }); +}); +``` diff --git a/frontend/src/App.vue b/frontend/src/App.vue index ccd898e..a85a3c2 100644 --- a/frontend/src/App.vue +++ b/frontend/src/App.vue @@ -1,4 +1,5 @@ diff --git a/frontend/src/api-enhanced.js b/frontend/src/api-enhanced.js new file mode 100644 index 0000000..d268fc3 --- /dev/null +++ b/frontend/src/api-enhanced.js @@ -0,0 +1,265 @@ +/** + * Enhanced API wrapper with integrated error handling and notifications + * + * This example shows how to use the error store and notification system together + * to provide comprehensive error handling and user feedback for API calls. + */ + +import { useErrorStore } from "@/stores/errors"; +import { useNotificationStore } from "@/stores/notifications"; +import { useLoadingStore } from "@/stores/loading"; +import Api from "./api"; + +export class ApiWithErrorHandling { + static async makeApiCall(apiFunction, options = {}) { + const { + // Error handling options + componentName = null, + showErrorNotifications = true, + showSuccessNotifications = true, + + // Loading options + showLoading = true, + loadingMessage = "Loading...", + + // Success options + successMessage = null, + successTitle = "Success", + + // Error options + errorTitle = "Error", + customErrorMessage = null, + + // Retry options + retryCount = 0, + retryDelay = 1000, + + // Operation identifier for tracking + operationKey = null, + } = options; + + const errorStore = useErrorStore(); + const notificationStore = useNotificationStore(); + const loadingStore = useLoadingStore(); + + // Generate operation key if not provided + const operation = operationKey || `api-${Date.now()}`; + + try { + // Clear any existing errors + if (componentName) { + errorStore.clearComponentError(componentName); + } + + // Show loading state + if (showLoading) { + if (componentName) { + loadingStore.setComponentLoading(componentName, true, loadingMessage); + } else { + loadingStore.startOperation(operation, loadingMessage); + } + } + + // Make the API call with retry logic + const result = await errorStore.handleApiCall(operation, apiFunction, { + showNotification: showErrorNotifications, + retryCount, + retryDelay, + }); + + // Show success notification + if (showSuccessNotifications && successMessage) { + notificationStore.addSuccess(successMessage, successTitle); + } + + return result; + } catch (error) { + // The error store has already handled the error notification + // But we can add custom handling here if needed + console.error("API call failed:", error); + + // Optionally show a custom error message + if (customErrorMessage && !showErrorNotifications) { + notificationStore.addError(customErrorMessage, errorTitle); + } + + // Re-throw the error so calling code can handle it if needed + throw error; + } finally { + // Always clear loading state + if (showLoading) { + if (componentName) { + loadingStore.setComponentLoading(componentName, false); + } else { + loadingStore.stopOperation(operation); + } + } + } + } + + // Convenience methods for common API operations + static async getClientStatusCounts(options = {}) { + return this.makeApiCall(() => Api.getClientStatusCounts(), { + operationKey: "client-status-counts", + componentName: "clients", + loadingMessage: "Loading client status data...", + successMessage: null, // Don't show success for data fetches + ...options, + }); + } + + static async getPaginatedClientDetails(paginationParams, filters, sorting, options = {}) { + return this.makeApiCall( + () => Api.getPaginatedClientDetails(paginationParams, filters, sorting), + { + operationKey: "client-table-data", + componentName: "dataTable", + loadingMessage: "Loading client data...", + successMessage: null, // Don't show success for data fetches + ...options, + }, + ); + } + + static async createClient(clientData, options = {}) { + return this.makeApiCall(() => Api.createClient(clientData), { + operationKey: "create-client", + componentName: "form", + loadingMessage: "Creating client...", + successMessage: "Client created successfully!", + errorTitle: "Failed to Create Client", + ...options, + }); + } + + static async getPaginatedJobDetails(paginationParams, filters, sorting, options = {}) { + return this.makeApiCall( + () => Api.getPaginatedJobDetails(paginationParams, filters, sorting), + { + operationKey: "job-table-data", + componentName: "jobs", + loadingMessage: "Loading job data...", + successMessage: null, + ...options, + }, + ); + } + + static async getPaginatedWarrantyData(paginationParams, filters, sorting, options = {}) { + return this.makeApiCall( + () => Api.getPaginatedWarrantyData(paginationParams, filters, sorting), + { + operationKey: "warranty-table-data", + componentName: "warranties", + loadingMessage: "Loading warranty data...", + successMessage: null, + ...options, + }, + ); + } + + static async getCityStateByZip(zipcode, options = {}) { + return this.makeApiCall(() => Api.getCityStateByZip(zipcode), { + operationKey: "zip-lookup", + componentName: "form", + loadingMessage: "Looking up location...", + successMessage: null, + errorTitle: "Zip Code Lookup Failed", + customErrorMessage: "Unable to find location for the provided zip code", + retryCount: 2, + retryDelay: 1000, + ...options, + }); + } +} + +/** + * Example usage in Vue components: + * + * + */ + +export default ApiWithErrorHandling; diff --git a/frontend/src/api-toast.js b/frontend/src/api-toast.js new file mode 100644 index 0000000..ac18ae4 --- /dev/null +++ b/frontend/src/api-toast.js @@ -0,0 +1,241 @@ +/** + * Enhanced API wrapper with PrimeVue Toast integration + * + * This provides a cleaner, simpler API error handling system using PrimeVue Toast + * instead of a complex custom notification system. + */ + +import { useErrorStore } from "@/stores/errors"; +import { useLoadingStore } from "@/stores/loading"; +import Api from "./api"; + +export class ApiWithToast { + static async makeApiCall(apiFunction, options = {}) { + const { + // Error handling options + componentName = null, + showErrorToast = true, + showSuccessToast = false, + + // Loading options + showLoading = true, + loadingMessage = "Loading...", + + // Success options + successMessage = null, + + // Error options + customErrorMessage = null, + + // Retry options + retryCount = 0, + retryDelay = 1000, + + // Operation identifier for tracking + operationKey = null, + rethrow = false, + } = options; + + const errorStore = useErrorStore(); + const loadingStore = useLoadingStore(); + + // Generate operation key if not provided + const operation = operationKey || `api-${Date.now()}`; + + try { + // Clear any existing errors + if (componentName) { + errorStore.clearComponentError(componentName); + } + + // Show loading state + if (showLoading) { + if (componentName) { + loadingStore.setComponentLoading(componentName, true, loadingMessage); + } else { + loadingStore.startOperation(operation, loadingMessage); + } + } + + // Make the API call with retry logic + let attempt = 0; + while (attempt <= retryCount) { + try { + const result = await apiFunction(); + + // Show success toast if requested + if (showSuccessToast && successMessage) { + errorStore.setSuccess(successMessage); + } + + return result; + } catch (error) { + attempt++; + + if (attempt <= retryCount) { + // Wait before retry + await new Promise((resolve) => setTimeout(resolve, retryDelay)); + continue; + } + + // Final attempt failed - handle error + if (componentName) { + errorStore.setComponentError(componentName, error, false); + } + + // Show error toast + if (showErrorToast) { + const errorMessage = customErrorMessage || this.extractErrorMessage(error); + errorStore.setGlobalError(new Error(errorMessage)); + } + + // Rethrow error if requested (default is to rethrow) + if (rethrow) { + throw error; + } + + // If not rethrowing, return null to indicate failure + return null; + } + } + } finally { + // Always clear loading state + if (showLoading) { + if (componentName) { + loadingStore.setComponentLoading(componentName, false); + } else { + loadingStore.stopOperation(operation); + } + } + } + } + + // Helper to extract meaningful error messages + static extractErrorMessage(error) { + if (typeof error === "string") { + return error; + } + + if (error?.response?.data?.message) { + return error.response.data.message; + } + + if (error?.message) { + return error.message; + } + + if (error?.request) { + return "Network error - please check your connection"; + } + + return "An unexpected error occurred"; + } + + // Convenience methods for common API operations + static async getClientStatusCounts(options = {}) { + return this.makeApiCall(() => Api.getClientStatusCounts(), { + operationKey: "client-status-counts", + componentName: "clients", + loadingMessage: "Loading client status data...", + showSuccessToast: false, // Don't show success for data fetches + ...options, + }); + } + + static async getPaginatedClientDetails(paginationParams, filters, sorting, options = {}) { + return this.makeApiCall( + () => Api.getPaginatedClientDetails(paginationParams, filters, sorting), + { + operationKey: "client-table-data", + componentName: "dataTable", + loadingMessage: "Loading client data...", + showSuccessToast: false, + ...options, + }, + ); + } + + static async createClient(clientData, options = {}) { + return this.makeApiCall(() => Api.createClient(clientData), { + operationKey: "create-client", + componentName: "form", + loadingMessage: "Creating client...", + showSuccessToast: true, + successMessage: "Client created successfully!", + ...options, + }); + } + + static async getPaginatedJobDetails(paginationParams, filters, sorting, options = {}) { + return this.makeApiCall( + () => Api.getPaginatedJobDetails(paginationParams, filters, sorting), + { + operationKey: "job-table-data", + componentName: "jobs", + loadingMessage: "Loading job data...", + showSuccessToast: false, + ...options, + }, + ); + } + + static async getPaginatedWarrantyData(paginationParams, filters, sorting, options = {}) { + return this.makeApiCall( + () => Api.getPaginatedWarrantyData(paginationParams, filters, sorting), + { + operationKey: "warranty-table-data", + componentName: "warranties", + loadingMessage: "Loading warranty data...", + showSuccessToast: false, + ...options, + }, + ); + } + + static async getCityStateByZip(zipcode, options = {}) { + return this.makeApiCall(() => Api.getCityStateByZip(zipcode), { + operationKey: "zip-lookup", + componentName: "form", + loadingMessage: "Looking up location...", + showSuccessToast: false, + customErrorMessage: "Unable to find location for the provided zip code", + retryCount: 2, + retryDelay: 1000, + ...options, + }); + } +} + +/** + * Simple usage examples: + * + * // Basic API call with automatic toast notifications + * try { + * const result = await ApiWithToast.getPaginatedClientDetails(pagination, filters, []); + * // Success - data loaded, no toast shown for data fetches + * } catch (error) { + * // Error toast automatically shown, component error set + * } + * + * // Create operation with success toast + * try { + * await ApiWithToast.createClient(formData); + * // Success toast shown automatically: "Client created successfully!" + * } catch (error) { + * // Error toast shown automatically with appropriate message + * } + * + * // Custom options + * await ApiWithToast.makeApiCall( + * () => someApiCall(), + * { + * componentName: 'myComponent', + * showSuccessToast: true, + * successMessage: 'Operation completed!', + * retryCount: 3, + * customErrorMessage: 'Custom error message' + * } + * ); + */ + +export default ApiWithToast; diff --git a/frontend/src/api.js b/frontend/src/api.js index af21730..215d0fa 100644 --- a/frontend/src/api.js +++ b/frontend/src/api.js @@ -3,12 +3,14 @@ import ApiUtils from "./apiUtils"; const ZIPPOPOTAMUS_BASE_URL = "https://api.zippopotam.us/us"; const FRAPPE_PROXY_METHOD = "custom_ui.api.proxy.request"; const FRAPPE_UPSERT_ESTIMATE_METHOD = "custom_ui.api.db.estimates.upsert_estimate"; +const FRAPPE_GET_JOBS_METHOD = "custom_ui.api.db.get_jobs"; const FRAPPE_UPSERT_JOB_METHOD = "custom_ui.api.db.jobs.upsert_job"; const FRAPPE_UPSERT_INVOICE_METHOD = "custom_ui.api.db.invoices.upsert_invoice"; const FRAPPE_UPSERT_CLIENT_METHOD = "custom_ui.api.db.clients.upsert_client"; const FRAPPE_GET_CLIENT_STATUS_COUNTS_METHOD = "custom_ui.api.db.clients.get_client_status_counts"; const FRAPPE_GET_CLIENT_TABLE_DATA_METHOD = "custom_ui.api.db.clients.get_clients_table_data"; const FRAPPE_GET_CLIENT_METHOD = "custom_ui.api.db.clients.get_client"; +const FRAPPE_GET_CLIENT_NAMES_METHOD = "custom_ui.api.db.clients.get_client_names"; class Api { static async request(frappeMethod, args = {}) { @@ -19,10 +21,12 @@ class Api { let response = await frappe.call(request); response = ApiUtils.toCamelCaseObject(response); console.log("DEBUG: API - Request Response: ", response); - return response.message; + if (response.message.status && response.message.status === "error") { + throw new Error(response.message.message); + } + return response.message.data; } catch (error) { - console.error("DEBUG: API - Request Error: ", error); - // Re-throw the error so calling code can handle it + console.error("ERROR: API - Request Error: ", error); throw error; } } @@ -145,7 +149,7 @@ class Api { console.log("DEBUG: API - Sending job options to backend:", options); - const result = await this.request("custom_ui.api.db.get_jobs", { options }); + const result = await this.request(FRAPPE_GET_JOBS_METHOD, { options }); return result; } @@ -238,11 +242,8 @@ class Api { return doc; } - static async getCustomerNames() { - const customers = await this.getDocsList("Customer", ["name"]); - const customerNames = customers.map((customer) => customer.name); - console.log("DEBUG: API - Fetched Customer Names: ", customerNames); - return customerNames; + static async getCustomerNames(type) { + return await this.request(FRAPPE_GET_CLIENT_NAMES_METHOD, { type }); } static async getCompanyNames() { diff --git a/frontend/src/components/SideBar.vue b/frontend/src/components/SideBar.vue index 0256b89..d592855 100644 --- a/frontend/src/components/SideBar.vue +++ b/frontend/src/components/SideBar.vue @@ -11,24 +11,21 @@ import { PathArrowSolid, Clock, HistoricShield, + Developer, } from "@iconoir/vue"; import SpeedDial from "primevue/speeddial"; const router = useRouter(); const modalStore = useModalStore(); -const categories = [ - { name: "Home", icon: Home, url: "/" }, - { name: "Calendar", icon: Calendar, url: "/calendar" }, - { name: "Clients", icon: Community, url: "/clients" }, - { name: "Jobs", icon: Hammer, url: "/jobs" }, - { name: "Routes", icon: PathArrowSolid, url: "/routes" }, - { name: "Time Sheets", icon: Clock, url: "/timesheets" }, - { name: "Warranties", icon: HistoricShield, url: "/warranties" }, + +const developmentButtons = ref([ { - name: "Create New", - icon: MultiplePagesPlus, + label: "Error Handling Demo", + command: () => { + router.push("/dev/error-handling-demo"); + }, }, -]; +]); const createButtons = ref([ { @@ -70,6 +67,22 @@ const createButtons = ref([ }, }, ]); + +const categories = ref([ + { name: "Home", icon: Home, url: "/" }, + { name: "Calendar", icon: Calendar, url: "/calendar" }, + { name: "Clients", icon: Community, url: "/clients" }, + { name: "Jobs", icon: Hammer, url: "/jobs" }, + { name: "Routes", icon: PathArrowSolid, url: "/routes" }, + { name: "Time Sheets", icon: Clock, url: "/timesheets" }, + { name: "Warranties", icon: HistoricShield, url: "/warranties" }, + { + name: "Create New", + icon: MultiplePagesPlus, + buttons: createButtons, + }, + { name: "Development", icon: Developer, buttons: developmentButtons }, +]); const handleCategoryClick = (category) => { router.push(category.url); }; @@ -94,7 +107,7 @@ const handleCategoryClick = (category) => {