feat: enhance documentation for crop utility functions and image crop control methods

ricwilson · ricwilson · commit 90d2c4528019 · 2025-06-19T11:54:00.000-04:00
diff --git a/ImageCrop/ImageCrop/components/imageCropControl.tsx b/ImageCrop/ImageCrop/components/imageCropControl.tsx
@@ -1,5 +1,5 @@
 import * as React from "react";
-import { convertToPixelCrop, Crop, PixelCrop } from "react-image-crop";
+import { Crop, PixelCrop } from "react-image-crop";
 import "react-image-crop/dist/ReactCrop.css";
 import { usePcfContext } from "../services/pcfContext";
 import { IImageCropControlProps } from "../types/imageCropTypes";
diff --git a/ImageCrop/ImageCrop/index.ts b/ImageCrop/ImageCrop/index.ts
@@ -50,6 +50,12 @@ export class ImageCrop implements ComponentFramework.StandardControl<IInputs, IO
         this._reactRoot = ReactDOM.createRoot(this._container);
     }
 
+    /**
+     * Returns the output schema for the control, used by Power Apps to validate the shape of output properties.
+     * This is required for controls with object-typed outputs (e.g., actionOutput).
+     * @param context The PCF context object
+     * @returns A promise resolving to the output schema object
+     */
     public async getOutputSchema(context: ComponentFramework.Context<IInputs>): Promise<Record<string, unknown>> {
         return Promise.resolve({
             actionOutput: ActionOutputSchema
@@ -74,14 +80,22 @@ export class ImageCrop implements ComponentFramework.StandardControl<IInputs, IO
         );
     }
 
-    // Callback for crop complete
+    /**
+     * Callback invoked when a crop operation is completed.
+     * Sets the crop result and triggers output notification.
+     * @param results The base64 string of the cropped image
+     */
     public onCropComplete = (results: string) => {
         this._actionCropComplete = true;
         this._cropResults = results;
         this._notifyOutputChanged();
     };
 
-    // Callback for drag start
+    /**
+     * Callback invoked when a drag operation starts on the crop area.
+     * Sets the action output to 'dragStart' and pointer coordinates, then notifies output change.
+     * @param e PointerEvent from the drag start
+     */
     public onDragStart = (e: PointerEvent) => {
         this._actionDragStart = true;
         this._actionOutput = {
@@ -92,7 +106,11 @@ export class ImageCrop implements ComponentFramework.StandardControl<IInputs, IO
         this._notifyOutputChanged();
     };
 
-    // Callback for drag end
+    /**
+     * Callback invoked when a drag operation ends on the crop area.
+     * Sets the action output to 'dragEnd' and pointer coordinates, then notifies output change.
+     * @param e PointerEvent from the drag end
+     */
     public onDragEnd = (e: PointerEvent) => {
         this._actionDragEnd = true;
         this._actionOutput = {
diff --git a/ImageCrop/ImageCrop/utils/cropUtils.ts b/ImageCrop/ImageCrop/utils/cropUtils.ts
@@ -1,5 +1,17 @@
+/**
+ * Utility functions for crop calculations in the Image Cropper PCF control.
+ * Provides helpers for centering and constraining aspect ratio crops.
+ */
 import { Crop, makeAspectCrop, centerCrop } from "react-image-crop";
 
+/**
+ * Calculates a centered crop rectangle with a given aspect ratio, sized to fit within the media dimensions.
+ * The crop will be 90% of the media width, centered, and constrained to the aspect ratio.
+ * @param mediaWidth The width of the image or video
+ * @param mediaHeight The height of the image or video
+ * @param aspect The desired aspect ratio (width / height)
+ * @returns A Crop object representing the centered aspect crop
+ */
 export function centerAspectCrop(
   mediaWidth: number,
   mediaHeight: number,
