diff --git a/webapp/src/components/App/Singlestudy/explore/Debug/utils.ts b/webapp/src/components/App/Singlestudy/explore/Debug/utils.ts index e97f0e00a7..a6e3798806 100644 --- a/webapp/src/components/App/Singlestudy/explore/Debug/utils.ts +++ b/webapp/src/components/App/Singlestudy/explore/Debug/utils.ts @@ -22,9 +22,7 @@ export type TreeData = Record | string; // Utils //////////////////////////////////////////////////////////////// -/** - * Maps file types and folder to their corresponding icon components. - */ +//Maps file types and folder to their corresponding icon components. const iconByFileType: Record = { matrix: DatasetIcon, json: DataObjectIcon, @@ -34,8 +32,9 @@ const iconByFileType: Record = { /** * Gets the icon component for a given file type or folder. - * @param {FileType | "folder"} type - The type of the file or "folder". - * @returns {SvgIconComponent} The corresponding icon component. + * + * @param type - The type of the file or "folder". + * @returns The corresponding icon component. */ export const getFileIcon = (type: FileType | "folder"): SvgIconComponent => { return iconByFileType[type] || TextSnippetIcon; @@ -43,8 +42,9 @@ export const getFileIcon = (type: FileType | "folder"): SvgIconComponent => { /** * Determines the file type based on the tree data. - * @param {TreeData} treeData - The data of the tree item. - * @returns {FileType | "folder"} The determined file type or "folder". + * + * @param treeData - The data of the tree item. + * @returns The determined file type or "folder". */ export const determineFileType = (treeData: TreeData): FileType | "folder" => { if (typeof treeData === "string") { @@ -63,8 +63,9 @@ export const determineFileType = (treeData: TreeData): FileType | "folder" => { /** * Filters out specific keys from the tree data. - * @param {TreeData} data - The original tree data. - * @returns {TreeData} The filtered tree data. + * + * @param data - The original tree data. + * @returns The filtered tree data. */ export const filterTreeData = (data: TreeData): TreeData => { const excludedKeys = new Set(["Desktop", "study", "logs"]); diff --git a/webapp/src/components/App/Singlestudy/explore/Modelization/Areas/Hydro/utils.ts b/webapp/src/components/App/Singlestudy/explore/Modelization/Areas/Hydro/utils.ts index ed8457afe4..815c491120 100644 --- a/webapp/src/components/App/Singlestudy/explore/Modelization/Areas/Hydro/utils.ts +++ b/webapp/src/components/App/Singlestudy/explore/Modelization/Areas/Hydro/utils.ts @@ -210,6 +210,7 @@ export const MATRICES: Matrices = { /** * Generates an array of column names from 0 to 100, optionally with a suffix. + * * @param columnSuffix The suffix to append to the column names. * @returns An array of strings representing column names from 0 to 100. */ diff --git a/webapp/src/components/App/Singlestudy/explore/Modelization/Areas/common/utils.ts b/webapp/src/components/App/Singlestudy/explore/Modelization/Areas/common/utils.ts index 8528245c84..9231804f53 100644 --- a/webapp/src/components/App/Singlestudy/explore/Modelization/Areas/common/utils.ts +++ b/webapp/src/components/App/Singlestudy/explore/Modelization/Areas/common/utils.ts @@ -20,17 +20,21 @@ export const saveField = R.curry( /** * Custom aggregation function summing the values of each row, - * to display enabled and installed capacity in the same cell. - * @param colHeader - the column header - * @param rows - the column rows to aggregate - * @returns a string with the sum of enabled and installed capacity. - * @example "100/200" - * @see https://www.material-react-table.com/docs/guides/aggregation-and-grouping#custom-aggregation-functions + * to display enabled and installed capacity in the same cell. This function is + * designed for use with Material React Table's custom aggregation feature, allowing + * the combination of enabled and installed capacities into a single cell. + * + * @returns A string representing the sum of enabled and installed capacity in the format "enabled/installed". + * @example + * Assuming an aggregation of rows where enabled capacities sum to 100 and installed capacities sum to 200 + * "100/200" + * + * @see https://www.material-react-table.com/docs/guides/aggregation-and-grouping#custom-aggregation-functions for more information on custom aggregation functions in Material React Table. */ export const capacityAggregationFn = < T extends ThermalClusterWithCapacity | RenewableClusterWithCapacity, >(): MRT_AggregationFn => { - return (colHeader, rows) => { + return (_colHeader, rows) => { const { enabledCapacitySum, installedCapacitySum } = rows.reduce( (acc, row) => { acc.enabledCapacitySum += row.original.enabledCapacity ?? 0; diff --git a/webapp/src/components/App/Singlestudy/explore/Modelization/Map/utils.ts b/webapp/src/components/App/Singlestudy/explore/Modelization/Map/utils.ts index 742ebe152a..677eeee143 100644 --- a/webapp/src/components/App/Singlestudy/explore/Modelization/Map/utils.ts +++ b/webapp/src/components/App/Singlestudy/explore/Modelization/Map/utils.ts @@ -83,7 +83,15 @@ export const getTextColor = (bgColor: RGB): string => { //////////////////////////////////////////////////////////////// /** - * Sets the graph nodes from the nodes data + * Custom hook to compute and return nodes with adjusted positions based on the current layer and view settings. + * It adjusts node positions to ensure they are correctly positioned in the graph based on the current zoom level and layer. + * Additionally, it calculates the color for each node, supporting layer-specific color adjustments. + * + * @param nodes Array of nodes to render. + * @param width Width of the rendering area. + * @param height Height of the rendering area. + * @param currentLayerId The ID of the current layer, used to adjust node positions and colors. + * @returns Array of nodes with updated positions and colors for rendering. */ export function useRenderNodes( nodes: StudyMapNode[], diff --git a/webapp/src/components/App/Singlestudy/explore/TableModeList/utils.ts b/webapp/src/components/App/Singlestudy/explore/TableModeList/utils.ts index bcd307a954..68fe41c256 100644 --- a/webapp/src/components/App/Singlestudy/explore/TableModeList/utils.ts +++ b/webapp/src/components/App/Singlestudy/explore/TableModeList/utils.ts @@ -21,7 +21,13 @@ export interface TableTemplate { //////////////////////////////////////////////////////////////// /** - * Allows to check columns validity for specified type. + * Allows to check columns validity for specified type. Creates a table template with unique ID, name, type, and columns configuration. + * This function is intended to define the structure and type of data that a table can hold. + * + * @param name The name of the table template. + * @param type The type of the table, determining the allowed columns and their configuration based on the table mode type. + * @param columns The configuration of columns specific to the table mode type. + * @returns A table template object including a unique ID, name, type, and columns configuration. */ export function createTableTemplate( name: string, diff --git a/webapp/src/components/common/GroupedDataTable/utils.ts b/webapp/src/components/common/GroupedDataTable/utils.ts index aad96a3784..0f31c1243d 100644 --- a/webapp/src/components/common/GroupedDataTable/utils.ts +++ b/webapp/src/components/common/GroupedDataTable/utils.ts @@ -20,9 +20,9 @@ export interface TRow { * If the base value is found in the list of existing values, it appends a number * in the format `(n)` to the base value, incrementing `n` until a unique value is found. * - * @param {string} baseValue - The original base value to check. - * @param {string[]} existingValues - The list of existing values to check against. - * @returns {string} A unique value. + * @param baseValue The original base value to check for uniqueness. + * @param existingValues The list of existing values to check against for duplicates. + * @returns A unique value derived from the base value by appending a number in parentheses, if necessary. */ export const generateNextValue = ( baseValue: string, @@ -54,14 +54,14 @@ export const generateNextValue = ( * based on the given original value and the existing values in tableData. * * If the property is "name", the function appends " - copy" to the original value. - * If the property is "id", the function uses nameToId to get the base value. + * If the property is "id", the function uses `nameToId` to get the base value. * - * This function leverages generateNextValue to ensure the uniqueness of the value. + * This function leverages `generateNextValue` to ensure the uniqueness of the value. * - * @param {"name" | "id"} property - The property for which the unique value is generated. - * @param {string} originalValue - The original value of the specified property. - * @param {TRow[]} tableData - The existing table data to check against. - * @returns {string} A unique value for the specified property. + * @param property The property for which the unique value is generated, either "name" or "id". + * @param originalValue The original value of the specified property. + * @param tableData The existing table data to check against for ensuring uniqueness. + * @returns A unique value for the specified property. */ export const generateUniqueValue = ( property: "name" | "id", diff --git a/webapp/src/components/common/SplitLayoutView.tsx b/webapp/src/components/common/SplitLayoutView.tsx index 62c1209e24..b30edd8ae9 100644 --- a/webapp/src/components/common/SplitLayoutView.tsx +++ b/webapp/src/components/common/SplitLayoutView.tsx @@ -8,7 +8,13 @@ interface Props { } /** - * @deprecated Use SplitView instead. + * Renders a split layout view with a fixed left column and a flexible right column. + * This component is deprecated and should be replaced with the `SplitView` component for enhanced functionality and flexibility. + * + * @deprecated Use `SplitView` instead for better layout management and customization options. + * + * @param props The component props including `left` and `right` components to render in the split layout, and `sx` for styling. + * @returns A React component that displays a split layout with left and right sections. */ function SplitLayoutView(props: Props) { const { left, right, sx } = props; diff --git a/webapp/src/components/common/SplitView/index.tsx b/webapp/src/components/common/SplitView/index.tsx index 3e1249af91..7550c527f4 100644 --- a/webapp/src/components/common/SplitView/index.tsx +++ b/webapp/src/components/common/SplitView/index.tsx @@ -11,8 +11,8 @@ export interface SplitViewProps { } /** - * Renders a resizable split view layout. It can be configured - * for both horizontal and vertical directions. + * Renders a resizable split view layout, configurable for both horizontal and vertical directions. + * * @see {@link SplitViewProps} for the properties it accepts. * * @example @@ -20,6 +20,13 @@ export interface SplitViewProps { * * * + * + * @param props The component props. + * @param props.children Child components to be rendered within the split views. + * @param props.direction The orientation of the split view ("horizontal" or "vertical"). + * @param props.sizes Initial sizes of each view in percentages. The array must sum to 100 and match the number of children. + * @param props.gutterSize The size of the gutter between split views. Defaults to 4. + * @returns A React component displaying a split layout view with resizable panes. */ function SplitView({ children, diff --git a/webapp/src/hoc/reactHookFormSupport.tsx b/webapp/src/hoc/reactHookFormSupport.tsx index 282ce5358a..a0aec8f2b2 100644 --- a/webapp/src/hoc/reactHookFormSupport.tsx +++ b/webapp/src/hoc/reactHookFormSupport.tsx @@ -67,19 +67,36 @@ export type ReactHookFormSupportProps< shouldUnregister?: never; }; +/** + * Provides React Hook Form support to a field editor component, enhancing it with form control and validation capabilities. + * It integrates custom validation logic, value transformation, and handles form submission state. + * + * @param options - Configuration options for the hook support. + * @param options.preValidate - A function that pre-validates the value before the main validation. + * @param options.setValueAs - A function that transforms the value before setting it into the form. + * @returns A function that takes a field editor component and returns a new component wrapped with React Hook Form functionality. + */ function reactHookFormSupport( options: ReactHookFormSupport = {}, ) { const { preValidate, setValueAs = R.identity } = options; /** - * Wrap in a higher component the specified field editor component + * Wraps the provided field editor component with React Hook Form functionality, + * applying the specified pre-validation and value transformation logic. + * + * @param FieldEditor - The field editor component to wrap. + * @returns The wrapped component with added React Hook Form support. */ function wrapWithReactHookFormSupport< TProps extends FieldEditorProps, >(FieldEditor: React.ComponentType) { /** - * The wrapper component + * The wrapper component that integrates React Hook Form capabilities with the original field editor. + * It manages form control registration, handles value changes and blurring with custom logic, and displays validation errors. + * + * @param props - The props of the field editor, extended with React Hook Form and custom options. + * @returns The field editor component wrapped with React Hook Form functionality. */ function ReactHookFormSupport< TFieldValues extends FieldValues = FieldValues, diff --git a/webapp/src/hooks/useNavigateOnCondition.ts b/webapp/src/hooks/useNavigateOnCondition.ts index 6930e1ecf6..036ce0e72f 100644 --- a/webapp/src/hooks/useNavigateOnCondition.ts +++ b/webapp/src/hooks/useNavigateOnCondition.ts @@ -23,18 +23,17 @@ interface UseNavigateOnConditionOptions { } /** - * A React hook for conditional navigation using react-router-dom. + * A React hook for conditional navigation using react-router-dom. This hook allows for navigating to a different route + * based on custom logic encapsulated in a `shouldNavigate` function. It observes specified dependencies and triggers navigation + * when they change if the conditions defined in `shouldNavigate` are met. * - * @function - * @name useNavigateOnCondition - * - * @param {Object} options - Configuration options for the hook. - * @param {DependencyList} options.deps - An array of dependencies that the effect will observe. - * @param {To} options.to - The target location to navigate to, it could be a route as a string or a relative numeric location. - * @param {function} [options.shouldNavigate] - An optional function that returns a boolean to determine whether navigation should take place. + * @param options - Configuration options for the hook. + * @param options.deps - An array of dependencies that the effect will observe. + * @param options.to - The target location to navigate to, which can be a route as a string or a relative numeric location. + * @param options.shouldNavigate - An optional function that returns a boolean to determine whether navigation should take place. Defaults to a function that always returns true. * * @example - * - Basic usage + * Basic usage * useNavigateOnCondition({ * deps: [someDependency], * to: '/some-route', diff --git a/webapp/src/services/utils/index.ts b/webapp/src/services/utils/index.ts index 0386ebef79..863363a44f 100644 --- a/webapp/src/services/utils/index.ts +++ b/webapp/src/services/utils/index.ts @@ -248,7 +248,12 @@ export const sortByName = (list: T[]): T[] => { }; /** - * @deprecated This function is deprecated. Please use nameToId instead. + * Converts a name string to an ID format. + * + * @deprecated Please use `nameToId` instead. + * + * @param name The string to transform. + * @returns The transformed ID string. */ export const transformNameToId = (name: string): string => { let duppl = false; @@ -290,6 +295,7 @@ export const transformNameToId = (name: string): string => { * Converts a name string to a valid ID string. * Replacing any characters that are not alphanumeric or -_,()& with a space, * trimming the resulting string, and converting it to lowercase. + * * @param name The name string to convert to an ID. * @returns The resulting ID string. */ diff --git a/webapp/src/utils/fnUtils.ts b/webapp/src/utils/fnUtils.ts index d232d83246..bf6a806760 100644 --- a/webapp/src/utils/fnUtils.ts +++ b/webapp/src/utils/fnUtils.ts @@ -1,6 +1,17 @@ /** - * Use it instead of disabling ESLint rule. + * A utility function designed to be used as a placeholder or stub. It can be used in situations where you might + * otherwise be tempted to disable an ESLint rule temporarily, such as when you need to pass a function that + * does nothing (for example, as a default prop in React components or as a no-operation callback). + * + * By using this function, you maintain code cleanliness and intention clarity without directly suppressing + * linting rules. + * + * @param args - Accepts any number of arguments of any type, but does nothing with them. + * + * @example + * Can be used as an empty event handler in React components + * */ export function voidFn(...args: TArgs) { - // Do nothing + // Intentionally empty, as its purpose is to do nothing. } diff --git a/webapp/src/utils/stringUtils.ts b/webapp/src/utils/stringUtils.ts index 1b83ea6b6d..823829fb29 100644 --- a/webapp/src/utils/stringUtils.ts +++ b/webapp/src/utils/stringUtils.ts @@ -11,9 +11,14 @@ export const isSearchMatching = R.curry( ); /** - * Formats a string with values. + * Formats a string by replacing placeholders with specified values. + * + * @param str - The string containing placeholders in the format `{placeholder}`. + * @param values - An object mapping placeholders to their replacement values. + * @returns The formatted string with all placeholders replaced by their corresponding values. + * * @example - * format("Hello {name}", { name: "John" }); // returns "Hello John" + * format("Hello {name}", { name: "John" }); // Returns: "Hello John" */ export function format(str: string, values: Record): string { return str.replace(/{([a-zA-Z0-9]+)}/g, (_, key) => values[key]);