From 59e66750df9cfadfe945125688de52640cabf5ed Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Wed, 12 Nov 2025 10:38:18 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`Product?= =?UTF-8?q?sCrudDemoPage`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @getabalewKemaw. * https://github.com/getabalewKemaw/MeshebeshaDesignFrontend/pull/6#issuecomment-3521249062 The following files were modified: * `app/admin/stock/page.tsx` * `app/products/[id]/page.tsx` * `app/products/page.tsx` * `components/products/StockManagementDashboard.tsx` * `lib/api/products.ts` * `lib/hooks/useProducts.ts` --- app/admin/stock/page.tsx | 12 +++++++++- app/products/[id]/page.tsx | 10 +++++++- app/products/page.tsx | 10 +++++++- .../products/StockManagementDashboard.tsx | 12 +++++++++- lib/api/products.ts | 23 +++++++++++++++---- lib/hooks/useProducts.ts | 12 ++++++++-- 6 files changed, 68 insertions(+), 11 deletions(-) diff --git a/app/admin/stock/page.tsx b/app/admin/stock/page.tsx index e9721a8..aeaf388 100644 --- a/app/admin/stock/page.tsx +++ b/app/admin/stock/page.tsx @@ -11,6 +11,16 @@ import { useEffect } from "react"; import Navbar from "@/components/NavBar"; import StockManagementDashboard from "@/components/products/StockManagementDashboard"; +/** + * Stock management page component that renders the admin inventory dashboard and enforces admin-only access. + * + * If authentication is loading, displays a centered spinner. If authentication has finished and the user is not + * an admin, redirects to "/dashboard" and renders nothing. When the user is an admin, renders the page layout with + * Navbar and the StockManagementDashboard. + * + * @returns The page's React element: a centered loading spinner while auth is loading, `null` for non-admin users, + * or the admin dashboard layout when the user is an admin. + */ export default function StockManagementPage() { const { isAdmin, isLoading } = useAuth(); const router = useRouter(); @@ -42,4 +52,4 @@ export default function StockManagementPage() { ); -} +} \ No newline at end of file diff --git a/app/products/[id]/page.tsx b/app/products/[id]/page.tsx index 90151a6..fdb9a8d 100644 --- a/app/products/[id]/page.tsx +++ b/app/products/[id]/page.tsx @@ -6,6 +6,15 @@ import Navbar from "@/components/NavBar"; import { getPublicProductById, recordProductView } from "@/lib/api/products"; import type { ProductWithDetails, ProductMedia } from "@/types/product"; +/** + * Render a product detail page showing media, variants, and product metadata. + * + * Fetches the public product using the route `id`, displays loading or error states, + * shows primary media with a thumbnail strip, a gallery, and variant cards, and + * records a product view after a successful load. + * + * @returns A React element that renders the product detail page UI. + */ export default function ProductDetailPage() { const params = useParams<{ id: string }>(); const id = params?.id; @@ -159,4 +168,3 @@ export default function ProductDetailPage() { ); } - diff --git a/app/products/page.tsx b/app/products/page.tsx index 00fbaa6..a54d5dd 100644 --- a/app/products/page.tsx +++ b/app/products/page.tsx @@ -15,6 +15,15 @@ const DEFAULT_FILTERS = { limit: 12, }; +/** + * Renders the products listing page with search, category and price filters, and paginated product results. + * + * The component fetches filter options and product data when filters change, maintains loading and error states, + * and provides UI controls for searching, selecting categories, setting a price range, clearing filters, and + * navigating pages. + * + * @returns The rendered React element for the products listing page. + */ export default function ProductsPage() { const [products, setProducts] = useState([]); const [loading, setLoading] = useState(true); @@ -235,4 +244,3 @@ export default function ProductsPage() { ); } - diff --git a/components/products/StockManagementDashboard.tsx b/components/products/StockManagementDashboard.tsx index 0b7bcda..11f92f3 100644 --- a/components/products/StockManagementDashboard.tsx +++ b/components/products/StockManagementDashboard.tsx @@ -32,6 +32,16 @@ interface BulkUpdateItem { newStock: number; } +/** + * Stock management dashboard UI for viewing low-stock items and performing bulk stock updates. + * + * Displays low-stock and out-of-stock counts, a list of low-stock variants with search and export CSV capabilities, + * and a bulk update panel that lets users queue variants, edit target stock levels, and apply batched stock updates. + * + * Shows loading, error, empty, and success states and provides a refresh action to reload low-stock data. + * + * @returns The React element that renders the stock management dashboard. + */ export default function StockManagementDashboard() { const { lowStockItems, loading, error, refetch } = useLowStock(10); const [bulkUpdates, setBulkUpdates] = useState([]); @@ -389,4 +399,4 @@ export default function StockManagementDashboard() { ); -} +} \ No newline at end of file diff --git a/lib/api/products.ts b/lib/api/products.ts index e7edc5d..c189c63 100644 --- a/lib/api/products.ts +++ b/lib/api/products.ts @@ -74,7 +74,9 @@ export async function getProducts( } /** - * Get product by ID (admin) + * Fetches a product by its ID for admin access. + * + * @returns The product details wrapped in an `ApiResponse` */ export async function getProductById( id: string @@ -84,8 +86,16 @@ export async function getProductById( // ==================== PUBLIC BROWSE ==================== /** - * Get public product list with filters - * Supports: categoryId, search (q), minPrice, maxPrice, page, limit + * Fetches a paginated list of public products that match the provided filters. + * + * @param params - Filter and pagination options + * @param params.categoryId - ID of the category to filter products by + * @param params.q - Full-text search query + * @param params.minPrice - Minimum price to include + * @param params.maxPrice - Maximum price to include + * @param params.page - Page number for pagination + * @param params.limit - Number of items per page + * @returns A paginated response containing product details and pagination metadata. On failure `success` is `false` and `data` is an empty array. */ export async function getPublicProducts(params: { categoryId?: string; @@ -119,7 +129,10 @@ export async function getPublicProducts(params: { } /** - * Get public product details by ID + * Retrieve public product details for the specified product ID. + * + * @param id - The public product ID + * @returns The API response containing the product with details */ export async function getPublicProductById( id: string @@ -436,4 +449,4 @@ export async function updateMetrics(): Promise> { return apiCall('/api/v1/admin/products/analytics/update-metrics', { method: 'POST', }); -} +} \ No newline at end of file diff --git a/lib/hooks/useProducts.ts b/lib/hooks/useProducts.ts index 1b0421c..aac3d6b 100644 --- a/lib/hooks/useProducts.ts +++ b/lib/hooks/useProducts.ts @@ -339,7 +339,15 @@ export function useFilterOptions() { } /** - * Hook for low stock alerts + * Provide low-stock product variants for a given threshold and a refetch control. + * + * @param threshold - Stock level threshold used to determine which variants are considered low stock (default 10) + * @returns An object containing: + * - `lowStockItems`: the same array as `variants`, alias for low-stock variants + * - `variants`: array of `ProductVariant` representing low-stock variants + * - `loading`: `true` while a fetch is in progress, `false` otherwise + * - `error`: error message when a fetch fails, or `null` when there is no error + * - `refetch`: function to re-run the low-stock fetch with the current `threshold` */ export function useLowStock(threshold: number = 10) { const [variants, setVariants] = useState([]); @@ -387,4 +395,4 @@ export function useLowStock(threshold: number = 10) { error, refetch, }; -} +} \ No newline at end of file