From 946ce88fd024dcda7b7c469fc6a89f968f933a01 Mon Sep 17 00:00:00 2001 From: tureh1 <158090534+tureh1@users.noreply.github.com> Date: Thu, 11 Dec 2025 18:50:20 -0600 Subject: [PATCH] docs: Add comprehensive documentation to CartPage.razor- Added detailed file header explaining component purpose, features, and dependencies- Documented all form-bound properties (UpdateQuantityId, UpdateQuantityValue)- Added XML documentation for component lifecycle method OnInitializedAsync- Documented computed properties TotalPrice and TotalQuantity- Added detailed remarks for CurrentOrPendingQuantity method explaining UX improvement- Documented UpdateQuantityAsync method with form handling details- Included usage notes about StreamRendering and progressive enhancementThis addresses issue #913 by providing complete documentation for the cart component,improving maintainability and helping developers understand the cart functionality.Closes #913 --- .../Components/Pages/Cart/CartPage.razor | 129 +++++++++++++++++- 1 file changed, 125 insertions(+), 4 deletions(-) diff --git a/src/WebApp/Components/Pages/Cart/CartPage.razor b/src/WebApp/Components/Pages/Cart/CartPage.razor index bd8ccfab7..56b665aad 100644 --- a/src/WebApp/Components/Pages/Cart/CartPage.razor +++ b/src/WebApp/Components/Pages/Cart/CartPage.razor @@ -1,4 +1,45 @@ -@page "/cart" +@* + ============================================================================= + CART PAGE COMPONENT + ============================================================================= + + Purpose: + Displays the user's shopping cart (shopping bag) with functionality to view, + update quantities, and proceed to checkout in the AdventureWorks e-commerce application. + + Features: + 1. Displays all items in the shopping cart with product images, names, and prices + 2. Allows users to update item quantities using a numeric input field + 3. Shows real-time calculations of item totals and cart summary + 4. Provides navigation to checkout and continue shopping + 5. Supports progressive enhancement with enhanced forms + + Route: /cart + Authentication: Required (Authorize attribute) + Stream Rendering: Enabled for improved performance + + Dependencies: + - NavigationManager: Handles page navigation within the application + - BasketState: Manages cart state and basket operations + - IProductImageUrlProvider: Provides product image URLs for display + + UI Components: + - Responsive cart layout with header, items list, and summary panel + - Form-based quantity updates with anti-forgery protection + - Real-time price calculations as quantities change + + Form Handlers: + - "update-cart": Handles quantity updates via form submission + - Uses enhanced forms (data-enhance) for progressive enhancement + + Example URL: https://localhost:5001/cart + + Related Pages: + - Catalog pages for continuing shopping + - Checkout page for completing purchases +*@ + +@page "/cart" @inject NavigationManager Nav @inject BasketState Basket @inject IProductImageUrlProvider ProductImages @@ -85,27 +126,107 @@ @code { private IReadOnlyCollection? basketItems; + /// + /// Gets or sets the product ID for quantity updates from form submission. + /// + /// + /// This property is automatically bound from form data when the "update-cart" + /// form is submitted. It identifies which product's quantity is being updated. + /// The value corresponds to the ProductId of the BasketItem. + /// [SupplyParameterFromForm] public int? UpdateQuantityId { get; set; } + /// + /// Gets or sets the new quantity value from form submission. + /// + /// + /// This property is automatically bound from form data when the "update-cart" + /// form is submitted. It contains the new quantity value entered by the user. + /// A value of 0 will remove the item from the cart. + /// [SupplyParameterFromForm] public int? UpdateQuantityValue { get; set; } + /// + /// Initializes the component by loading the user's basket items. + /// + /// + /// This lifecycle method is called when the component is first initialized. + /// It asynchronously retrieves the current user's basket items from the + /// BasketState service and updates the component's state. + /// + /// The StreamRendering attribute enables streaming rendering for this component, + /// allowing the UI to show loading state before all data is loaded. + /// protected override async Task OnInitializedAsync() { basketItems = await Basket.GetBasketItemsAsync(); } + /// + /// Calculates the total price of all items in the cart. + /// + /// + /// The sum of (UnitPrice * Quantity) for all basket items, or null if the basket is empty or not loaded. + /// + /// + /// This computed property automatically recalculates whenever basketItems changes. + /// The result is formatted for display with two decimal places. + /// private decimal? TotalPrice => basketItems?.Sum(i => i.Quantity * i.UnitPrice); + + /// + /// Calculates the total quantity of all items in the cart. + /// + /// + /// The sum of quantities for all basket items, or null if the basket is empty or not loaded. + /// + /// + /// This computed property is used to display the item count badge in the cart summary header. + /// It automatically updates when basketItems changes. + /// private decimal? TotalQuantity => basketItems?.Sum(i => i.Quantity); - // While an update post is in process, we want to show the pending quantity, not the one - // that is committed to the cart (otherwise the UI briefly shows the old data) + /// + /// Determines which quantity to display for a product during form submission. + /// + /// The ID of the product to check. + /// The current quantity stored in the cart. + /// + /// The pending quantity from the form if this product is being updated, + /// otherwise the current cart quantity. + /// + /// + /// This method provides a better user experience by showing the pending + /// quantity value during form submission, preventing the UI from briefly + /// displaying old data while the update is processing. + /// + /// Example: If user changes quantity from 2 to 3 and clicks Update, + /// this method returns 3 immediately instead of showing 2 during processing. + /// private int CurrentOrPendingQuantity(int productId, int cartQuantity) => UpdateQuantityId.GetValueOrDefault(-1) == productId ? UpdateQuantityValue!.Value : cartQuantity; + /// + /// Handles the form submission for updating item quantities in the cart. + /// + /// Task representing the asynchronous operation. + /// + /// This method is triggered when the "update-cart" form is submitted. + /// It performs the following operations: + /// 1. Updates the quantity for the specified product in the BasketState + /// 2. Refreshes the basket items from the service + /// 3. Updates the UI with the new quantities and totals + /// + /// The form uses progressive enhancement (data-enhance) for better + /// performance and user experience. + /// + /// Error handling: If the update fails, the BasketState service is + /// responsible for error handling and user notification. + /// private async Task UpdateQuantityAsync() { var id = UpdateQuantityId!.Value; @@ -113,4 +234,4 @@ await Basket.SetQuantityAsync(id, quantity); basketItems = await Basket.GetBasketItemsAsync(); } -} +} \ No newline at end of file