From 159d4cb0f0c32ca2701468af2dfd3b5c8aa04a6d Mon Sep 17 00:00:00 2001 From: Jineshbansal <732005jinesh@gmail.com> Date: Tue, 4 Feb 2025 07:54:53 +0530 Subject: [PATCH 1/5] frontend: tsdocs: Add TSDoc comments to Tabs.tsx Signed-off-by: Jineshbansal <732005jinesh@gmail.com> --- frontend/src/components/common/Tabs.tsx | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/frontend/src/components/common/Tabs.tsx b/frontend/src/components/common/Tabs.tsx index d04792aeaad..2834c0f3d36 100644 --- a/frontend/src/components/common/Tabs.tsx +++ b/frontend/src/components/common/Tabs.tsx @@ -11,15 +11,18 @@ export interface Tab { component: ReactNode; } +/** + * Props interface for the `Tabs` component. + */ export interface TabsProps { - tabs: Tab[]; + tabs: Tab[]; // List of tabs to display tabProps?: { [propName: string]: any; - }; - defaultIndex?: number | null | boolean; - onTabChanged?: (tabIndex: number) => void; - sx?: SxProps; - ariaLabel: string; + }; // Optional props for the MuiTabs component + defaultIndex?: number | null | boolean; // Default selected tab index + onTabChanged?: (tabIndex: number) => void; // Callback for tab change + sx?: SxProps; // Optional styles + ariaLabel: string; // Accessibility label for the Tabs component } export default function Tabs(props: TabsProps) { From a1898001ea557121df44e31b0a7fccd81c2d3a5d Mon Sep 17 00:00:00 2001 From: Jineshbansal <732005jinesh@gmail.com> Date: Tue, 4 Feb 2025 07:55:37 +0530 Subject: [PATCH 2/5] frontend: tsdocs: Add TSDoc comments to LocaleSelect.tsx Signed-off-by: Jineshbansal <732005jinesh@gmail.com> --- .../src/i18n/LocaleSelect/LocaleSelect.tsx | 27 ++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/frontend/src/i18n/LocaleSelect/LocaleSelect.tsx b/frontend/src/i18n/LocaleSelect/LocaleSelect.tsx index 0ef1e6aa793..204075d3b24 100644 --- a/frontend/src/i18n/LocaleSelect/LocaleSelect.tsx +++ b/frontend/src/i18n/LocaleSelect/LocaleSelect.tsx @@ -7,6 +7,14 @@ import React from 'react'; import { useTranslation } from 'react-i18next'; import { supportedLanguages } from '../config'; + +/** + * Interface for the props used by the `LocaleSelect` component, which is responsible for rendering a locale selection UI. + * + * @param {boolean} [showTitle] - Optional flag to control whether the title of the locale selector is displayed. Defaults to `false`. + * @param {boolean} [showFullNames] - Optional flag to control whether to display full language names instead of language codes. Defaults to `false`. + * @param {FormControlProps} [formControlProps] - Optional properties to customize the `FormControl` component used for the locale selection. + */ export interface LocaleSelectProps { showTitle?: boolean; showFullNames?: boolean; @@ -14,7 +22,24 @@ export interface LocaleSelectProps { } /** - * A UI for selecting the locale with i18next + * A component that provides a UI for selecting the locale with `i18next`, allowing users to switch languages in the application. + * It uses Material UI components such as `FormControl`, `Select`, and `MenuItem` to render a dropdown for selecting a language. + * + * @remarks + * This component displays a locale selector with support for showing either the language code or the full language name, + * depending on the `showFullNames` prop. It also listens for language changes via the `i18next` library and updates the UI accordingly. + * + * @param {LocaleSelectProps} props - The properties for the `LocaleSelect` component. + * @param {boolean} [props.showTitle] - Optional flag to show the title of the locale selection. Defaults to `false`. + * @param {boolean} [props.showFullNames] - Optional flag to show the full names of the languages instead of their abbreviations. Defaults to `false`. + * @param {FormControlProps} [props.formControlProps] - Optional props for customizing the `FormControl` component used within the selector. + * + * @returns {ReactNode} A `FormControl` component containing a `Select` dropdown for changing the app's language. + * + * @example + * ```tsx + * + * ``` */ export default function LocaleSelect(props: LocaleSelectProps) { const { formControlProps, showFullNames } = props; From 4d21de74a28c27d4500205784310e67d09c96e49 Mon Sep 17 00:00:00 2001 From: Jineshbansal <732005jinesh@gmail.com> Date: Tue, 4 Feb 2025 07:56:38 +0530 Subject: [PATCH 3/5] frontend: tsdocs: Add TSDoc comments to ThemeProviderNexti18n.tsx Signed-off-by: Jineshbansal <732005jinesh@gmail.com> --- frontend/src/i18n/ThemeProviderNexti18n.tsx | 40 +++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/frontend/src/i18n/ThemeProviderNexti18n.tsx b/frontend/src/i18n/ThemeProviderNexti18n.tsx index 68f0ca5fdde..950ff6523b0 100644 --- a/frontend/src/i18n/ThemeProviderNexti18n.tsx +++ b/frontend/src/i18n/ThemeProviderNexti18n.tsx @@ -4,6 +4,21 @@ import React, { ReactNode, useEffect, useState } from 'react'; import { useTranslation } from 'react-i18next'; import { Loader } from '../components/common'; +/** + * Returns the Material UI locale object for the given language code. + * + * @remarks + * This method retrieves the locale configuration for a specific language supported by + * Material UI. It checks the provided language code against a predefined set of available locales, + * and returns the corresponding locale object. If the language code is not found, it defaults to + * English (`enUS`). + * + * @param locale - The language code for which the locale object is required (e.g., 'en', 'pt', 'es'). + * + * @returns The Material UI locale object corresponding to the provided language code. + * Defaults to `enUS` if the locale is not found in the predefined list. + */ + function getLocale(locale: string): typeof enUS { const LOCALES = { en: enUS, @@ -18,8 +33,29 @@ function getLocale(locale: string): typeof enUS { return locale in LOCALES ? LOCALES[locale as LocalesType] : LOCALES['en']; } -/** Like a ThemeProvider but uses reacti18next for the language selection - * Because Material UI is localized as well. +/** + * A custom theme provider component that integrates Material UI's theme with `react-i18next` for language selection. + * It ensures that both the theme and language are synchronized, providing seamless localization across the application. + * + * @remarks + * This component functions like a standard Material UI `ThemeProvider`, but it also listens for language changes using `react-i18next`. + * When the language is changed, the corresponding Material UI locale is applied to update the theme accordingly. + * This is essential for supporting multiple languages and ensuring the UI behaves correctly with Right-To-Left (RTL) languages. + * + * The component will show a loading state (``) until the i18n resources are ready for rendering. + * + * @param {object} props - The properties for the component. + * @param {Theme} props.theme - The Material UI theme object to be applied to the app. + * @param {ReactNode} props.children - The child components wrapped by this theme provider. + * + * @returns {ReactNode} The children components wrapped with the updated Material UI theme and language configurations. + * + * @example + * ```tsx + * + * + * + * ``` */ const ThemeProviderNexti18n: React.FunctionComponent<{ theme: Theme; From ca97604b761e02d842fdfc0649446be9fb6aa36f Mon Sep 17 00:00:00 2001 From: Jineshbansal <732005jinesh@gmail.com> Date: Mon, 17 Feb 2025 23:16:47 +0530 Subject: [PATCH 4/5] frontend: tsdocs: remove types in comments from ThemeProviderNexti18n.tsx and LocaleSelect.tsx Signed-off-by: Jineshbansal <732005jinesh@gmail.com> --- .../src/i18n/LocaleSelect/LocaleSelect.tsx | 29 +++++++++---------- frontend/src/i18n/ThemeProviderNexti18n.tsx | 26 ++++++++--------- 2 files changed, 27 insertions(+), 28 deletions(-) diff --git a/frontend/src/i18n/LocaleSelect/LocaleSelect.tsx b/frontend/src/i18n/LocaleSelect/LocaleSelect.tsx index 204075d3b24..6b5720a60d7 100644 --- a/frontend/src/i18n/LocaleSelect/LocaleSelect.tsx +++ b/frontend/src/i18n/LocaleSelect/LocaleSelect.tsx @@ -7,13 +7,12 @@ import React from 'react'; import { useTranslation } from 'react-i18next'; import { supportedLanguages } from '../config'; - /** * Interface for the props used by the `LocaleSelect` component, which is responsible for rendering a locale selection UI. - * - * @param {boolean} [showTitle] - Optional flag to control whether the title of the locale selector is displayed. Defaults to `false`. - * @param {boolean} [showFullNames] - Optional flag to control whether to display full language names instead of language codes. Defaults to `false`. - * @param {FormControlProps} [formControlProps] - Optional properties to customize the `FormControl` component used for the locale selection. + * + * @param showTitle - Optional flag to control whether the title of the locale selector is displayed. Defaults to `false`. + * @param showFullNames - Optional flag to control whether to display full language names instead of language codes. Defaults to `false`. + * @param formControlProps - Optional properties to customize the `FormControl` component used for the locale selection. */ export interface LocaleSelectProps { showTitle?: boolean; @@ -24,18 +23,18 @@ export interface LocaleSelectProps { /** * A component that provides a UI for selecting the locale with `i18next`, allowing users to switch languages in the application. * It uses Material UI components such as `FormControl`, `Select`, and `MenuItem` to render a dropdown for selecting a language. - * + * * @remarks - * This component displays a locale selector with support for showing either the language code or the full language name, + * This component displays a locale selector with support for showing either the language code or the full language name, * depending on the `showFullNames` prop. It also listens for language changes via the `i18next` library and updates the UI accordingly. - * - * @param {LocaleSelectProps} props - The properties for the `LocaleSelect` component. - * @param {boolean} [props.showTitle] - Optional flag to show the title of the locale selection. Defaults to `false`. - * @param {boolean} [props.showFullNames] - Optional flag to show the full names of the languages instead of their abbreviations. Defaults to `false`. - * @param {FormControlProps} [props.formControlProps] - Optional props for customizing the `FormControl` component used within the selector. - * - * @returns {ReactNode} A `FormControl` component containing a `Select` dropdown for changing the app's language. - * + * + * @param props - The properties for the `LocaleSelect` component. + * @param props.showTitle - Optional flag to show the title of the locale selection. Defaults to `false`. + * @param props.showFullNames - Optional flag to show the full names of the languages instead of their abbreviations. Defaults to `false`. + * @param props.formControlProps - Optional props for customizing the `FormControl` component used within the selector. + * + * @returns A `FormControl` component containing a `Select` dropdown for changing the app's language. + * * @example * ```tsx * diff --git a/frontend/src/i18n/ThemeProviderNexti18n.tsx b/frontend/src/i18n/ThemeProviderNexti18n.tsx index 950ff6523b0..edb4c3830ff 100644 --- a/frontend/src/i18n/ThemeProviderNexti18n.tsx +++ b/frontend/src/i18n/ThemeProviderNexti18n.tsx @@ -10,12 +10,12 @@ import { Loader } from '../components/common'; * @remarks * This method retrieves the locale configuration for a specific language supported by * Material UI. It checks the provided language code against a predefined set of available locales, - * and returns the corresponding locale object. If the language code is not found, it defaults to + * and returns the corresponding locale object. If the language code is not found, it defaults to * English (`enUS`). * * @param locale - The language code for which the locale object is required (e.g., 'en', 'pt', 'es'). - * - * @returns The Material UI locale object corresponding to the provided language code. + * + * @returns The Material UI locale object corresponding to the provided language code. * Defaults to `enUS` if the locale is not found in the predefined list. */ @@ -36,20 +36,20 @@ function getLocale(locale: string): typeof enUS { /** * A custom theme provider component that integrates Material UI's theme with `react-i18next` for language selection. * It ensures that both the theme and language are synchronized, providing seamless localization across the application. - * + * * @remarks - * This component functions like a standard Material UI `ThemeProvider`, but it also listens for language changes using `react-i18next`. + * This component functions like a standard Material UI `ThemeProvider`, but it also listens for language changes using `react-i18next`. * When the language is changed, the corresponding Material UI locale is applied to update the theme accordingly. * This is essential for supporting multiple languages and ensuring the UI behaves correctly with Right-To-Left (RTL) languages. - * + * * The component will show a loading state (``) until the i18n resources are ready for rendering. - * - * @param {object} props - The properties for the component. - * @param {Theme} props.theme - The Material UI theme object to be applied to the app. - * @param {ReactNode} props.children - The child components wrapped by this theme provider. - * - * @returns {ReactNode} The children components wrapped with the updated Material UI theme and language configurations. - * + * + * @param props - The properties for the component. + * @param props.theme - The Material UI theme object to be applied to the app. + * @param props.children - The child components wrapped by this theme provider. + * + * @returns The children components wrapped with the updated Material UI theme and language configurations. + * * @example * ```tsx * From 60cc7ef5350fa2cf58b94286940bc678e7a0e872 Mon Sep 17 00:00:00 2001 From: Jineshbansal <732005jinesh@gmail.com> Date: Fri, 21 Feb 2025 23:47:20 +0530 Subject: [PATCH 5/5] frontend: tsdocs: correct the tsdoc style comments for fields Signed-off-by: Jineshbansal <732005jinesh@gmail.com> --- frontend/src/components/common/Tabs.tsx | 36 ++++++++++++++++++++----- 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/frontend/src/components/common/Tabs.tsx b/frontend/src/components/common/Tabs.tsx index 2834c0f3d36..cdd8f886e92 100644 --- a/frontend/src/components/common/Tabs.tsx +++ b/frontend/src/components/common/Tabs.tsx @@ -15,14 +15,38 @@ export interface Tab { * Props interface for the `Tabs` component. */ export interface TabsProps { - tabs: Tab[]; // List of tabs to display + /** + * List of tabs to display. + */ + tabs: Tab[]; + + /** + * Optional props for the MuiTabs component. + */ tabProps?: { [propName: string]: any; - }; // Optional props for the MuiTabs component - defaultIndex?: number | null | boolean; // Default selected tab index - onTabChanged?: (tabIndex: number) => void; // Callback for tab change - sx?: SxProps; // Optional styles - ariaLabel: string; // Accessibility label for the Tabs component + }; + + /** + * Default selected tab index. + */ + defaultIndex?: number | null | boolean; + + /** + * Callback for tab change. + * @param tabIndex - The index of the selected tab. + */ + onTabChanged?: (tabIndex: number) => void; + + /** + * Optional styles. + */ + sx?: SxProps; + + /** + * Accessibility label for the Tabs component. + */ + ariaLabel: string; } export default function Tabs(props: TabsProps) {