From a692fa6f39f2ac20a745eb38e44c1156d976ca76 Mon Sep 17 00:00:00 2001 From: Zorin95670 Date: Wed, 7 May 2025 13:39:56 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D(frontend)=20Update=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Improve and add jsdoc. Signed-off-by: Zorin95670 --- CHANGELOG.md | 4 +++ src/frontend/apps/impress/src/api/APIError.ts | 30 ++++++++++++++++++- src/frontend/apps/impress/src/api/config.ts | 16 ++++++++++ src/frontend/apps/impress/src/api/helpers.tsx | 14 +++++++-- src/frontend/apps/impress/src/api/types.ts | 14 +++++++++ src/frontend/apps/impress/src/api/utils.ts | 19 +++++++++++- .../src/features/docs/doc-export/utils.ts | 13 ++++++-- .../features/service-worker/service-worker.ts | 14 +++++---- .../y-provider/src/servers/appServer.ts | 2 -- 9 files changed, 111 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d3acb9fa..a389c0c5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,10 @@ and this project adheres to - ✨ Add a custom callout block to the editor #892 - 🚩(frontend) version MIT only #911 +## Changed + +- 📝(frontend) Update documentation + ## [3.2.1] - 2025-05-06 ## Fixed diff --git a/src/frontend/apps/impress/src/api/APIError.ts b/src/frontend/apps/impress/src/api/APIError.ts index bed42a3e..6d7b92bc 100644 --- a/src/frontend/apps/impress/src/api/APIError.ts +++ b/src/frontend/apps/impress/src/api/APIError.ts @@ -1,17 +1,39 @@ +/** + * Generic interface for representing an API error structure. + * + * @template T - Optional type of additional data returned with the error. + */ interface IAPIError { + /** HTTP status code or API-defined error code */ status: number; + /** Optional list of error causes (e.g., validation issues) */ cause?: string[]; + /** Optional extra data provided with the error */ data?: T; } +/** + * Custom error class for representing API errors. + * Extends the native Error object with additional context such as HTTP status, + * causes, and extra data returned by the API. + * + * @template T - Optional type of the `data` field + */ export class APIError extends Error implements IAPIError { public status: IAPIError['status']; public cause?: IAPIError['cause']; public data?: IAPIError['data']; + /** + * Constructs a new APIError instance. + * + * @param message - The human-readable error message. + * @param status - The HTTP status code or equivalent. + * @param cause - (Optional) List of strings describing error causes. + * @param data - (Optional) Any additional data returned by the API. + */ constructor(message: string, { status, cause, data }: IAPIError) { super(message); - this.name = 'APIError'; this.status = status; this.cause = cause; @@ -19,6 +41,12 @@ export class APIError extends Error implements IAPIError { } } +/** + * Type guard for checking if a value is an instance of APIError. + * + * @param error - The value to check. + * @returns True if the value is an instance of APIError. + */ export const isAPIError = (error: unknown): error is APIError => { return error instanceof APIError; }; diff --git a/src/frontend/apps/impress/src/api/config.ts b/src/frontend/apps/impress/src/api/config.ts index 118f5814..916585e6 100644 --- a/src/frontend/apps/impress/src/api/config.ts +++ b/src/frontend/apps/impress/src/api/config.ts @@ -1,6 +1,22 @@ +/** + * Returns the base URL for the backend API. + * + * Priority: + * 1. Uses NEXT_PUBLIC_API_ORIGIN from environment variables if defined. + * 2. Falls back to the browser's window.location.origin if in a browser environment. + * 3. Defaults to an empty string if executed in a non-browser environment without the env variable. + * + * @returns The backend base URL as a string. + */ export const backendUrl = () => process.env.NEXT_PUBLIC_API_ORIGIN || (typeof window !== 'undefined' ? window.location.origin : ''); +/** + * Constructs the full base API URL, including the versioned path (e.g., `/api/v1.0/`). + * + * @param apiVersion - The version of the API (defaults to '1.0'). + * @returns The full versioned API base URL as a string. + */ export const baseApiUrl = (apiVersion: string = '1.0') => `${backendUrl()}/api/v${apiVersion}/`; diff --git a/src/frontend/apps/impress/src/api/helpers.tsx b/src/frontend/apps/impress/src/api/helpers.tsx index 9f304d2e..e36b9d41 100644 --- a/src/frontend/apps/impress/src/api/helpers.tsx +++ b/src/frontend/apps/impress/src/api/helpers.tsx @@ -22,9 +22,17 @@ export type DefinedInitialDataInfiniteOptionsAPI< >; /** - * @param param Used for infinite scroll pagination - * @param queryConfig - * @returns + * Custom React hook that wraps React Query's `useInfiniteQuery` for paginated API requests. + * + * @template T - Type of the request parameters. + * @template Q - Type of the API response, which must include an optional `next` field for pagination. + * + * @param {string} key - Unique key to identify the query in the cache. + * @param {(props: T & { page: number }) => Promise} api - Function that fetches paginated data from the API. It receives the params merged with a page number. + * @param {T} param - Static parameters to send with every API request (excluding the page number). + * @param {DefinedInitialDataInfiniteOptionsAPI} [queryConfig] - Optional configuration passed to `useInfiniteQuery` (e.g., stale time, cache time). + * + * @returns Return value of `useInfiniteQuery`, including data, loading state, fetchNextPage, etc. */ export const useAPIInfiniteQuery = ['next'] }>( key: string, diff --git a/src/frontend/apps/impress/src/api/types.ts b/src/frontend/apps/impress/src/api/types.ts index 5c48a797..e69a61a5 100644 --- a/src/frontend/apps/impress/src/api/types.ts +++ b/src/frontend/apps/impress/src/api/types.ts @@ -1,6 +1,20 @@ +/** + * Generic interface representing a paginated API response. + * + * Commonly used for endpoints that return list results with pagination metadata. + * + * @template T - The type of items in the `results` array. + */ export interface APIList { + /** Total number of items across all pages */ count: number; + + /** URL to the next page of results, if available (can be null or undefined) */ next?: string | null; + + /** URL to the previous page of results, if available (can be null or undefined) */ previous?: string | null; + + /** The list of items for the current page */ results: T[]; } diff --git a/src/frontend/apps/impress/src/api/utils.ts b/src/frontend/apps/impress/src/api/utils.ts index 8aea86ac..82bbe505 100644 --- a/src/frontend/apps/impress/src/api/utils.ts +++ b/src/frontend/apps/impress/src/api/utils.ts @@ -1,3 +1,16 @@ +/** + * Extracts error information from an HTTP `Response` object. + * + * This is typically used to parse structured error responses from an API + * and normalize them into a consistent format with `status`, `cause`, and optional `data`. + * + * @param response - The HTTP response object from `fetch()`. + * @param data - Optional custom data to include with the error output. + * @returns An object containing: + * - `status`: HTTP status code from the response + * - `cause`: A flattened list of error messages, or undefined if no body + * - `data`: The optional data passed in + */ export const errorCauses = async (response: Response, data?: unknown) => { const errorsBody = (await response.json()) as Record< string, @@ -18,7 +31,11 @@ export const errorCauses = async (response: Response, data?: unknown) => { }; /** - * Retrieves the CSRF token from the document's cookies. + * Retrieves the CSRF token from the browser's cookies. + * + * Assumes the CSRF token is stored as a cookie named "csrftoken". + * + * @returns The CSRF token string if found, otherwise `undefined`. */ export function getCSRFToken() { return document.cookie diff --git a/src/frontend/apps/impress/src/features/docs/doc-export/utils.ts b/src/frontend/apps/impress/src/features/docs/doc-export/utils.ts index 77bdf93b..82001e30 100644 --- a/src/frontend/apps/impress/src/features/docs/doc-export/utils.ts +++ b/src/frontend/apps/impress/src/features/docs/doc-export/utils.ts @@ -19,9 +19,16 @@ export function downloadFile(blob: Blob, filename: string) { } /** - * Convert SVG to PNG - * @param svgText - The SVG text to convert - * @returns The PNG data URL + * Converts an SVG string into a PNG image and returns it as a data URL. + * + * This function creates a canvas, parses the SVG, calculates the appropriate height + * to preserve the aspect ratio, and renders the SVG onto the canvas using Canvg. + * + * @param {string} svgText - The raw SVG markup to convert. + * @param {number} width - The desired width of the output PNG (height is auto-calculated to preserve aspect ratio). + * @returns {Promise} A Promise that resolves to a PNG image encoded as a base64 data URL. + * + * @throws Will throw an error if the canvas context cannot be initialized. */ export async function convertSvgToPng(svgText: string, width: number) { // Create a canvas and render the SVG onto it diff --git a/src/frontend/apps/impress/src/features/service-worker/service-worker.ts b/src/frontend/apps/impress/src/features/service-worker/service-worker.ts index b8950beb..5618eebe 100644 --- a/src/frontend/apps/impress/src/features/service-worker/service-worker.ts +++ b/src/frontend/apps/impress/src/features/service-worker/service-worker.ts @@ -38,11 +38,15 @@ setCacheNameDetails({ }); /** - * In development, use NetworkFirst strategy, in production use CacheFirst strategy - * We will be able to test the application in development without having to clear the cache. - * @param url - * @param options - * @returns strategy + * Chooses the appropriate caching strategy based on the environment and request context. + * + * - In **development**, or for **API requests**, or **HTML pages**, it returns a `NetworkFirst` strategy + * to prioritize fresh responses and ease debugging without needing to clear caches. + * - In **production** (for non-API, non-HTML content), it returns a `CacheFirst` strategy + * to favor performance and offline access. + * + * @param {NetworkFirstOptions | StrategyOptions} [options] - Configuration options for the caching strategy. + * @returns {NetworkFirst | CacheFirst} The selected Workbox strategy instance. */ const getStrategy = ( options?: NetworkFirstOptions | StrategyOptions, diff --git a/src/frontend/servers/y-provider/src/servers/appServer.ts b/src/frontend/servers/y-provider/src/servers/appServer.ts index 80077bb8..00532e03 100644 --- a/src/frontend/servers/y-provider/src/servers/appServer.ts +++ b/src/frontend/servers/y-provider/src/servers/appServer.ts @@ -17,8 +17,6 @@ import { logger } from '../utils'; /** * init the collaboration server. * - * @param port - The port on which the server listens. - * @param serverSecret - The secret key for API authentication. * @returns An object containing the Express app, Hocuspocus server, and HTTP server instance. */ export const initServer = () => {