doc: add more comments on new components

Author: aeltorio

client/src/pages/page-components/ActionCell.tsx

@@ -1,20 +1,70 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2025 Ronan LE MEILLAT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
 import { Button } from "@heroui/button";
 import { useTranslation } from "react-i18next";
 import ButtonAddFeedbackOrReturn from "@/components/button-add-feedback-or-return";
 import { PurchaseStatus } from "@/types/db";
 
+/**
+ * Props interface for the ActionCell component
+ * Defines the structure of data and callback functions needed
+ */
 interface ActionCellProps {
+  /** The purchase item data containing status information */
   item: PurchaseStatus;
+  /** Whether the current user has write permissions (null while loading) */
   hasWritePermission: boolean | null;
+  /** Callback function to create feedback for a purchase */
   onCreateFeedback: (purchaseId: string, amount: number) => void;
+  /** Callback function to return/return a purchase */
   onReturnItem: (purchaseId: string, amount: number) => void;
+  /** Callback function to publish feedback for a purchase */
   onPublishFeedback: (purchaseId: string, amount: number) => void;
+  /** Callback function to refund a purchase */
   onRefundPurchase: (purchaseId: string, amount: number) => void;
 }
 
 /**
- * Component for rendering the action column in the purchase table
- * Shows different actions based on purchase status and user permissions
+ * ActionCell Component
+ *
+ * This component renders the action buttons for each row in the purchase table.
+ * The actions available depend on the purchase status and user permissions:
+ *
+ * - If the purchase is refunded: Shows "Refunded" status text
+ * - If no feedback exists and user has write permission: Shows buttons to create feedback or return item
+ * - If feedback exists but not published and user has write permission: Shows "Publish Feedback" button
+ * - If feedback is published and user has write permission: Shows "Refund" button
+ * - If user lacks write permission: Shows no actions
+ *
+ * The component uses conditional rendering to display appropriate actions based on:
+ * 1. Purchase status (refunded, hasFeedback, hasPublication)
+ * 2. User permissions (hasWritePermission)
+ * 3. Loading state (when permissions are still being checked)
+ *
+ * @param props - The component props containing item data and callback functions
+ * @returns JSX element representing the action cell content
  */
 export const ActionCell = ({
   item,
@@ -24,27 +74,35 @@ export const ActionCell = ({
   onPublishFeedback,
   onRefundPurchase,
 }: ActionCellProps) => {
+  // Hook to access translation functions for internationalization
   const { t } = useTranslation();
 
-  // Early return if permissions are still loading
+  // Show loading text while permissions are being checked
+  // This prevents showing incorrect action buttons during the loading phase
   if (hasWritePermission === null) {
     return <span className="text-gray-400">{t("loading")}</span>;
   }
 
-  // If refunded, show refunded status
+  // If the purchase has been refunded, show the refunded status
+  // No further actions are possible for refunded purchases
   if (item.refunded) {
     return <span className="text-green-500">{t("refunded")}</span>;
   }
 
-  // If no feedback and user has write permission, show create feedback/return options
+  // If no feedback exists and user has write permission,
+  // show the combined button for creating feedback or returning the item
   if (!item.hasFeedback && hasWritePermission) {
     return (
       <div className="flex gap-2">
+        {/* Custom button component that handles both feedback creation and item return */}
         <ButtonAddFeedbackOrReturn
           onAction={(key) => {
+            // Handle the action based on the key returned by the button
             if (key === "feedback") {
+              // Call the callback to create feedback for this purchase
               onCreateFeedback(item.purchase, item.amount);
             } else if (key === "return") {
+              // Call the callback to return this purchase
               onReturnItem(item.purchase, item.amount);
             }
           }}

client/src/pages/page-components/PurchaseIdCell.tsx

@@ -1,43 +1,105 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2025 Ronan LE MEILLAT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
 import { CopyButton } from "@/components/copy-button";
 import { EditIcon } from "@heroui/shared-icons";
 import { AuthenticationGuardWithPermission } from "@/components/auth0";
 
+/**
+ * Props interface for the PurchaseIdCell component
+ * Defines the structure of data and callback functions needed
+ */
 interface PurchaseIdCellProps {
+  /** The unique identifier of the purchase */
   purchaseId: string;
+  /** Whether this purchase has been published (affects link generation availability) */
   hasPublication: boolean;
+  /** Callback function to edit the purchase */
   onEditPurchase: (purchaseId: string) => void;
+  /** Callback function to generate a public link for the purchase */
   onGenerateLink: (purchaseId: string) => void;
 }
 
 /**
- * Component for rendering the purchase ID cell with copy button, edit button, and link generation
+ * PurchaseIdCell Component
+ *
+ * This component renders the purchase ID cell in the purchase table.
+ * It displays the purchase ID with interactive features based on user permissions and purchase status.
+ *
+ * Features:
+ * - Displays the purchase ID as clickable text (if publication exists)
+ * - Clicking the ID generates a public link (only available for published purchases)
+ * - Includes a copy button to copy the purchase ID to clipboard
+ * - Shows an edit icon for admin users to modify the purchase
+ * - Uses authentication guard to restrict edit functionality to admin users only
+ *
+ * The component combines multiple UI elements:
+ * 1. Clickable purchase ID (when publication exists)
+ * 2. CopyButton for easy ID copying
+ * 3. EditIcon with authentication guard for admin editing
+ *
+ * @param props - The component props containing purchase data and callback functions
+ * @returns JSX element representing the purchase ID cell with interactive features
  */
 export const PurchaseIdCell = ({
   purchaseId,
   hasPublication,
   onEditPurchase,
   onGenerateLink,
 }: PurchaseIdCellProps) => {
+  // Determine if the user can generate a public link
+  // Link generation is only available for purchases that have been published
   const canGenerateLink = hasPublication;
 
   return (
     <>
       <div className="flex items-center">
+        {/* Purchase ID display - clickable if publication exists */}
         <div
+          // Apply clickable styling only if link generation is available
           className={canGenerateLink ? "cursor-pointer hover:underline text-blue-500" : ""}
           onClick={() => {
+            // Generate public link when clicked (only if publication exists)
             if (canGenerateLink) {
               onGenerateLink(purchaseId);
             }
           }}
         >
           {purchaseId}
         </div>
+
+        {/* Action buttons container */}
         <div className="flex flex-col">
+          {/* Copy button to copy purchase ID to clipboard */}
           <CopyButton value={purchaseId} />
+
+          {/* Edit button - only visible to admin users */}
           <AuthenticationGuardWithPermission permission={import.meta.env.ADMIN_PERMISSION}>
             <EditIcon
+              // Click handler to open edit modal
               onClick={() => onEditPurchase(purchaseId)}
+              // Styling classes for the edit icon (HeroUI styling)
               className="group inline-flex items-center justify-center box-border appearance-none select-none whitespace-nowrap font-normal subpixel-antialiased overflow-hidden tap-highlight-transparent transform-gpu data-[pressed=true]:scale-[0.97] cursor-pointer outline-hidden data-[focus-visible=true]:z-10 data-[focus-visible=true]:outline-2 data-[focus-visible=true]:outline-focus data-[focus-visible=true]:outline-offset-2 text-tiny rounded-small px-0 transition-transform-colors-opacity motion-reduce:transition-none bg-transparent data-[hover=true]:bg-default/40 min-w-4 w-4 h-4 relative z-50 text-zinc-300 bottom-0 left-2"
             />
           </AuthenticationGuardWithPermission>

client/src/pages/page-components/StatusCell.tsx

@@ -1,19 +1,66 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2025 Ronan LE MEILLAT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
 import { Tooltip } from "@heroui/tooltip";
 import { CopyButton } from "@/components/copy-button";
 import { Transparent1x1WebpPixel } from "@/components/icons";
 import { useTranslation } from "react-i18next";
 
+/**
+ * Props interface for the StatusCell component
+ * Defines the structure of data needed to display status with optional screenshot
+ */
 interface StatusCellProps {
+  /** The main text to display in the cell */
   text: string;
+  /** Optional screenshot URL for the purchase */
   screenshot?: string;
+  /** Optional screenshot summary URL (for additional context) */
   screenshotSummary?: string;
+  /** Translation key for the copy button tooltip */
   copyTooltipKey: "copy-screenshot" | "copy-screenshots";
+  /** Callback function when screenshot is clicked */
   onScreenshotClick: (screenshot: string | string[]) => void;
 }
 
 /**
- * Component for rendering table cells that show status text with optional screenshot copy button
- * Includes tooltip for screenshot viewing and copy button with tooltip
+ * StatusCell Component
+ *
+ * This component renders table cells that display status text with optional screenshot functionality.
+ * It provides a user-friendly way to view and copy screenshots associated with purchases.
+ *
+ * Features:
+ * - Displays the main status text (e.g., "Yes", "No", or description)
+ * - Shows a tooltip when hovering over the text indicating it can be clicked to view screenshot
+ * - Includes a copy button to copy screenshot URLs to clipboard
+ * - Handles both single screenshots and screenshot pairs (main + summary)
+ *
+ * The component uses HeroUI's Tooltip component to provide helpful user guidance
+ * and a custom CopyButton component for copying screenshot data.
+ *
+ * @param props - The component props containing text, screenshot data, and callbacks
+ * @returns JSX element representing the status cell with optional screenshot functionality
  */
 export const StatusCell = ({
   text,
@@ -22,31 +69,40 @@ export const StatusCell = ({
   copyTooltipKey,
   onScreenshotClick,
 }: StatusCellProps) => {
+  // Hook to access translation functions for internationalization
   const { t } = useTranslation();
 
   return (
     <div className="flex items-center justify-between">
+      {/* Main text content with click-to-view functionality */}
       <Tooltip content={t("click-to-see-the-screenshot")}>
         <span
           className="flex-1 cursor-pointer"
           onClick={() => {
+            // Handle click to show screenshot(s)
+            // If both main screenshot and summary exist, show both
             if (screenshotSummary && screenshot) {
               onScreenshotClick([screenshot, screenshotSummary]);
             } else if (screenshot) {
+              // Otherwise show just the main screenshot
               onScreenshotClick(screenshot);
             }
           }}
         >
           {text}
         </span>
       </Tooltip>
+
+      {/* Copy button for screenshot URLs - only shown if screenshot exists */}
       {screenshot && (
         <Tooltip content={t(copyTooltipKey)}>
           <CopyButton
+            // Prepare the value to copy - either single screenshot or array of screenshots
             value={screenshotSummary && screenshot
               ? [screenshot, screenshotSummary || Transparent1x1WebpPixel]
               : screenshot
             }
+            // Indicate that this is image data for proper clipboard handling
             isImage={true}
             showToast={true}
             toastText={t("copied-to-clipboard")}