From f0f7a9f8e14233737b89e089b4aab640494b592e Mon Sep 17 00:00:00 2001 From: "komment-ai[bot]" <122626893+komment-ai[bot]@users.noreply.github.com> Date: Wed, 3 Jul 2024 18:06:34 +0000 Subject: [PATCH 1/3] Added comments to 13 functions across 6 files --- apps/react/app/App.tsx | 114 ++++++++++++++++++ packages/react/rollup.config.js | 66 ++++++++++ .../src/components/ConfirmCloseModal.tsx | 48 ++++++++ packages/react/src/components/Spinner.tsx | 14 +++ packages/react/src/index.ts | 9 ++ packages/react/src/utils/styleInject.ts | 21 ++++ 6 files changed, 272 insertions(+) diff --git a/apps/react/app/App.tsx b/apps/react/app/App.tsx index 032aff9e..6152f6cd 100644 --- a/apps/react/app/App.tsx +++ b/apps/react/app/App.tsx @@ -18,9 +18,63 @@ import styles from './page.module.css' attachStyleSheet({ nonce: 'flatfile-abc123' }) // add custom nonce +/** + * @description Is a React component that provides a portal interface to Flatfile, + * enabling listeners and plugins to interact with the portal. It renders a button + * for opening or closing the portal and allows users to set the label of an listener + * using a drop-down menu. + * + * @returns {HTML div element} a React component that displays a portal with several + * sheets, including a hooked sheet that sets an email field to a specific value. + * + * * `
` - This is the main container element for the + * Flatfile application. It contains all the other elements. + * * `
` - This element contains buttons and + * labels related to the portal. The button with the label "CLOSE" or "OPEN" opens + * or closes the portal iFrame window, respectively. Two buttons with labels "blue + * listener" and "green listener" are also present, which are not explained in this + * output. + * * `` - This + * button is used to toggle the state of the portal iFrame window. When the button + * is clicked, the `toggleOpen` function is called, which in turn calls the `closePortal` + * or `openPortal` function depending on the current state of the portal. + * * `` - This button + * is used to set the label for the blue listener. When clicked, the `setLabel` + * function is called with the value "blue". + * * `` - This + * button is used to set the label for the green listener. When clicked, the `setLabel` + * function is called with the value "green". + * * `` - This element contains the Flatfile workbook + * instance and its configuration options. It renders the `Document` and `Workbook` + * elements inside it. + * * `` - This element renders the Flatfile + * document instance with the specified configuration options. The `defaultPage` + * property specifies that the first page of the document should be rendered. + * * `` - This element renders the Flatfile workbook + * instance with the specified configuration options. The `name` property specifies + * the name of the workbook, and the `metadata` property specifies the metadata for + * the workbook. The `sidebarConfig` property specifies that the sidebar should be shown. + * * `` - This + * element renders a single sheet inside the Flatfile workbook instance with the + * specified configuration options. The `slug` property specifies the slug for the + * sheet, and the `name` property specifies the display name of the sheet. + * * ` {...}}>` - This element is used to render a + * single sheet inside the Flatfile workbook instance with a custom record hook. When + * the hook is called, it takes the record as an argument and can perform any logic + * needed for the record. + * * ` {...}}>` - This element is used to render a + * single sheet inside the Flatfile workbook instance with a custom submit hook. When + * the hook is called, it takes the sheet as an argument and can perform any logic + * needed for the sheet. + */ const App = () => { const { open, openPortal, closePortal } = useFlatfile() const [label, setLabel] = useState('Rock') + /** + * @description Updates the open state of a portal by calling either `closePortal` + * or `openPortal`, depending on whether the `reset` parameter is set to `false`. + */ const toggleOpen = () => { open ? closePortal({ reset: false }) : openPortal() } @@ -98,6 +152,28 @@ const App = () => { }} > + {/** + * @description Generates high-quality documentation for given code and enables + * submission and record hooks on separate sheets within the workbook. + * + * @param {object} config - Workbook's configuration, which includes setting various + * properties of the Workbook and its sheets, such as name, email, and record hooks. + * + * @param {`AsyncFunction`.} onSubmit - 3rd sheet submitted by the user, which will + * log the sheet's data to the console in a structured format using `{ sheet }`. + * + * * `async (sheet) => { console.log('onSubmit from', { sheet }); }`: This is an + * asynchronous function that logs a message to the console with the `onSubmit` + * function as an argument, along with its parameters (`{ sheet }`). The `console.log()` + * statement will execute after the `onSubmit` function is called, and it will log + * the value of `sheet`. + * * `config={{ ...workbook, name: 'ALEX’S WORKBOOK' }}`: This sets the `name` + * property of the `Workbook` configuration to `'ALEX’S WORKBOOK'`. + * + * @param {object} onRecordHooks - 2-dimensional array of record hook functions for + * each sheet in the workbook, where each function updates the `email` property of + * the records before they are saved to the corresponding sheet. + */} { ], ]} > + {/** + * @description Defines a new sheet with the given default page and configuration, + * and sets an onRecordHook to modify email values for records, and an onSubmit hook + * to log information when the sheet is submitted. + * + * @param {object} config - configuration for a new worksheet, including its slug and + * name, and overrides any defaults provided by the `workbook` object. + * + * @param {asynchronous function that returns a/an Google Sheets record.} onRecordHook + * - 4-ary function that gets called each time a new record is created or updated + * within the `Contacts3` sheet, allowing you to perform arbitrary actions on the + * newly created or updated records before they are persisted in the underlying storage. + * + * * `(record) => {...}` denotes an inline hook that performs actions on the current + * record. + * * `record.set('email', 'SHEET 3 RECORDHOOK')` modifies the `email` field of the + * current record by setting it to `'SHEET 3 RECORDHOOK'`. + * + * @param {object} onSubmit - callback function that is triggered when the changes + * made to the sheet are committed or saved. + */} { console.log('onSubmit from Sheet 3', { sheet }) }} /> + {/** + * @description Sets up a Google Sheets document with configuration for sheet 4, + * including setting an onRecordHook function to update a record's email field, and + * an onSubmit function to log information about the submitted sheet. + * + * @param {object} config - 0th sheet of the workbook, providing its slug and name. + * + * @param {functions reference.} onRecordHook - function to be called when a new + * record is created, where it sets the 'email' field of the record to `'SHEET 4 RECORDHOOK'`. + * + * * `(record)`: The current record being processed in the hook. It is an object + * with fields corresponding to the defined `onRecordHook` schema. + * * `'SHEET 4 RECORDHOOK'`: The value of the `email` field for the current record. + * + * @param {object} onSubmit - `console.log` statement, which will log an event + * notification to the console whenever a change is made in sheet 4. + */} void} .onConfirm - function to be executed when the user confirms + * the exit action. + * + * @param {() => void} .onCancel - function to be executed when the cancel button is + * clicked inside the modal window. + * + * @param {string} .exitText - text to be displayed in the modal's body for confirmation + * before closing the modal. + * + * @param {string} .exitTitle - title displayed above the modal when it is dismissed, + * typically providing a concise and informative description of the action being + * confirmed or cancelled. + * + * @param {string} .exitPrimaryButtonText - text to display on the primary button of + * the close confirmation modal, which is typically labeled as "OK" or "Save Changes". + * + * @param {string} .exitSecondaryButtonText - text to be displayed inside the secondary + * button that is located within the close confirm modal. + * + * @returns {HTMLDivElement} a modal component with a heading, text, primary and + * secondary buttons. + * + * * `onConfirm`: A function that will be called when the primary button is clicked. + * * `onCancel`: A function that will be called when the secondary button is clicked + * or when the user cancels the modal. + * * `exitText`: The text to display in the modal for the exit message. + * * `exitTitle`: The title to display in the modal for the exit message. + * * `exitPrimaryButtonText`: The text to display on the primary button in the modal. + * * `exitSecondaryButtonText`: The text to display on the secondary button in the + * modal. + * + * The returned output is a JSX element with a `div` container that contains the + * modal layout. The `div` element with the class `flatfile_outer-shell` contains the + * outer layer of the modal, while the `div` element with the class + * `flatfile_close-confirm-modal-inner` contains the inner layout of the modal. Inside + * the inner layout, there are three elements: a heading with the class + * `flatfile_modal-heading`, some text with the class `flatfile_modal-text`, and a + * button group containing two buttons with the classes `flatfile_button` and + * `flatfile_secondary`. The `onCancel` function is triggered when the secondary + * button is clicked or when the user cancels the modal, while the `onConfirm` function + * is triggered when the primary button is clicked. + */ export const ConfirmCloseModal = ({ onConfirm, onCancel, diff --git a/packages/react/src/components/Spinner.tsx b/packages/react/src/components/Spinner.tsx index 12b146b8..efb47eb9 100644 --- a/packages/react/src/components/Spinner.tsx +++ b/packages/react/src/components/Spinner.tsx @@ -1,5 +1,19 @@ import React from 'react' +/** + * @description Renders an animated spinner icon with the given class name and test + * ID for use in React applications. + * + * @returns {HTMLDivElement} an HTML `
` element with a class of `spinner` and a + * data-testid of `"spinner-icon"`." + * + * * `className`: This is a string that represents the CSS class name for the spinner + * element. + * * `data-testid`: This is an attribute that assigns a unique identifier to the + * spinner element, allowing developers to easily identify and manipulate it in their + * code. + * * `
`: This is the HTML element that represents the spinner itself. + */ const Spinner = () => { return
} diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts index f3472fb5..65f1b06f 100644 --- a/packages/react/src/index.ts +++ b/packages/react/src/index.ts @@ -14,6 +14,15 @@ export * from './components' export * from './hooks' export type { ISidebarConfig, ISpace, ISpaceInfo, IThemeConfig, IUserInfo } +/** + * @description Inserts a CSS stylesheet into the page using the `styleInject` method, + * passing in the stylesheet and any optional parameters for insertion position and + * nonce. + * + * @param {object} options - settings for inserting the stylesheet at a particular + * location on the page and includes an optional nonce value used to verify the + * integrity of the stylesheet contents. + */ export function attachStyleSheet(options?: { insertAt?: 'top' nonce?: string diff --git a/packages/react/src/utils/styleInject.ts b/packages/react/src/utils/styleInject.ts index 98101e18..0c108e96 100644 --- a/packages/react/src/utils/styleInject.ts +++ b/packages/react/src/utils/styleInject.ts @@ -1,5 +1,26 @@ // adapted from https://github.com/egoist/style-inject +/** + * @description Creates a new `style` element and injects it into the Document Object + * Model (DOM) at either the beginning or end of the head section, based on the + * `insertAt` parameter. It also sets an optional `nonce` attribute to validate the + * styles. + * + * @param {string} css - CSS content that will be injected into the HTML document's + * head tag using the `styleInject` function. + * + * @param {'top'} .insertAt - location where the generated style rule should be + * inserted into the `` element of the HTML document, with `'top'` indicating + * insertion at the top of the `` element and any other value specifying an + * explicit position. + * + * @param {string} .nonce - nonce, which is an arbitrary value used to prevent caching + * of stylesheets and ensure they are reevaluated by the browser each time they are + * requested, helping protect against cross-site scripting (XSS) attacks. + * + * @returns {any} a newly created `