@bigbinary/neeto-commons-frontend 2.0.58 → 2.0.60

package/configs/scripts/jsdoc-builder/constants.mjs

@@ -0,0 +1,42 @@
+/* eslint-disable @bigbinary/neeto/no-dangling-constants */
+import { complement, startsWith } from "ramda";
+
+export const REMARK_NODE_TYPES = {
+  HTML: "html",
+  PARAGRAPH: "paragraph",
+  CODE: "code",
+  HEADING: "heading",
+  TEXT: "text",
+  INLINE_CODE: "inlineCode",
+};
+
+export const BABEL_NODE_TYPES = { IDENTIFIER: "Identifier" };
+
+export const SUBHEADING_PATTERN = { type: REMARK_NODE_TYPES.HEADING, depth: 2 };
+export const HTML_PATTERN = { type: REMARK_NODE_TYPES.HTML };
+export const IMG_PATTERN = {
+  type: REMARK_NODE_TYPES.HTML,
+  value: startsWith("<img"),
+};
+export const CODE_PATTERN = { type: REMARK_NODE_TYPES.CODE };
+export const PARAGRAPH_PATTERN = { type: REMARK_NODE_TYPES.PARAGRAPH };
+export const HTML_EXCEPT_IMG_PATTERN = {
+  type: REMARK_NODE_TYPES.HTML,
+  value: complement(startsWith("<img")),
+};
+export const INLINE_CODE_PATTERN = { type: REMARK_NODE_TYPES.INLINE_CODE };
+export const TEXT_PATTERN = { type: REMARK_NODE_TYPES.TEXT };
+export const DOCS_FOLDER_NAME = "docs";
+export const TYPES_FOLDER_NAME = "typeTemplates";
+export const EXPORTED_TYPES_FOLDER_NAME = ""; // root
+
+export const JSDOC_IMG_HEIGHT = "200";
+export const JSDOC_IMG_WIDTH = "300";
+
+export const DOUBLE_LINE_BREAK_WITH_LEADING_COMMENT = "\n *\n";
+export const LINE_BREAK = "\n";
+export const JSDOC_EXAMPLE_TAG = "@example ";
+export const JSDOC_END_EXAMPLE_TAG = "@endexample";
+export const ASTERISK = "*";
+export const ASTERISK_WITH_SPACES = " * ";
+export const WHITESPACE_REGEX = /\s/g;

package/configs/scripts/jsdoc-builder/index.mjs

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+
+import _generate from "@babel/generator";
+import _traverse from "@babel/traverse";
+import * as babelTypes from "@babel/types";
+
+import {
+  DOCS_FOLDER_NAME,
+  EXPORTED_TYPES_FOLDER_NAME,
+  TYPES_FOLDER_NAME,
+} from "./constants.mjs";
+import {
+  buildEntityTitleToEntityDescMap,
+  getFileContent,
+  getFileNameList,
+  parseMarkdown,
+  parseTypeFile,
+  syncTypeFiles,
+  defaultTypeFileTraverser,
+} from "./utils.mjs";
+
+const traverse = _traverse.default;
+const generate = _generate.default;
+
+const buildJsdoc = ({
+  customTypeFileTraverser = defaultTypeFileTraverser,
+  exportedTypesFolderName = EXPORTED_TYPES_FOLDER_NAME,
+} = {}) => {
+  const fileNamesInsideDocs = getFileNameList(path.resolve(DOCS_FOLDER_NAME));
+  const typeFileNames = fs.readdirSync(path.resolve(TYPES_FOLDER_NAME));
+
+  syncTypeFiles(exportedTypesFolderName);
+
+  const entityTitleToDescMapOfAllFiles = {};
+
+  fileNamesInsideDocs.forEach(docFileName => {
+    const fileContent = getFileContent(docFileName);
+    const markdownAST = parseMarkdown(fileContent);
+
+    buildEntityTitleToEntityDescMap(
+      markdownAST.children,
+      entityTitleToDescMapOfAllFiles
+    );
+  });
+
+  // eslint-disable-next-line consistent-return
+  typeFileNames.forEach(typeFileName => {
+    const typeFileContent = getFileContent(
+      path.join(exportedTypesFolderName, typeFileName)
+    );
+    const typeFileAST = parseTypeFile(typeFileContent);
+
+    customTypeFileTraverser({
+      typeFileName,
+      typeFileAST,
+      entityTitleToDescMapOfAllFiles,
+      babelTraverse: traverse,
+      babelCodeGenerator: generate,
+      babelTypes,
+    });
+  });
+
+  console.log("Successfully added JSDoc comments to type files.");
+};
+
+export default buildJsdoc;

package/configs/scripts/jsdoc-builder/utils.mjs

@@ -0,0 +1,218 @@
+import fs from "fs";
+import path from "path";
+
+import * as babelParser from "@babel/parser";
+import { curry, __, mergeLeft } from "ramda";
+import remarkParse from "remark-parse";
+import unified from "unified";
+
+import {
+  ASTERISK,
+  ASTERISK_WITH_SPACES,
+  CODE_PATTERN,
+  DOUBLE_LINE_BREAK_WITH_LEADING_COMMENT,
+  EXPORTED_TYPES_FOLDER_NAME,
+  HTML_EXCEPT_IMG_PATTERN,
+  IMG_PATTERN,
+  JSDOC_EXAMPLE_TAG,
+  JSDOC_END_EXAMPLE_TAG,
+  JSDOC_IMG_HEIGHT,
+  JSDOC_IMG_WIDTH,
+  LINE_BREAK,
+  PARAGRAPH_PATTERN,
+  SUBHEADING_PATTERN,
+  TYPES_FOLDER_NAME,
+  WHITESPACE_REGEX,
+} from "./constants.mjs";
+import * as babelTypes from "@babel/types";
+import _traverse from "@babel/traverse";
+import _generate from "@babel/generator";
+
+import { matches } from "../../../pure.cjs.js";
+
+const traverse = _traverse.default;
+const generate = _generate.default;
+
+const removeSpaces = string => string.replace(WHITESPACE_REGEX, "");
+
+const addLeadingCommentForTextWithLineBreaks = ({
+  text,
+  addCommentForFirstItem = true,
+  addDoubleLineBreaks = true,
+}) => {
+  if (!hasLineBreaks(text)) return addLeadingComment(text);
+  const joinString = addDoubleLineBreaks
+    ? DOUBLE_LINE_BREAK_WITH_LEADING_COMMENT
+    : LINE_BREAK;
+
+  return text
+    .split(LINE_BREAK)
+    .map((item, idx) => {
+      if (!addCommentForFirstItem && idx === 0) return item;
+
+      return addLeadingComment(item);
+    })
+    .join(joinString);
+};
+
+const addLeadingComment = (text, trimWhiteSpace = false) =>
+  (trimWhiteSpace ? ASTERISK : ASTERISK_WITH_SPACES) + text;
+
+const transformCode = node => {
+  let text = "";
+  text += addLeadingComment(JSDOC_EXAMPLE_TAG);
+  text += DOUBLE_LINE_BREAK_WITH_LEADING_COMMENT;
+  text += addLeadingCommentForTextWithLineBreaks({
+    text: removeCommentTags(node.value),
+    addDoubleLineBreaks: false,
+  });
+  text += LINE_BREAK;
+  text += addLeadingComment(JSDOC_END_EXAMPLE_TAG);
+  text += LINE_BREAK;
+
+  return text;
+};
+
+const hasLineBreaks = text => text?.includes(LINE_BREAK);
+
+const getParagraphChildrenText = node => {
+  const children = node.children;
+  if (children.length === 1) return children[0].value;
+
+  return children.map(child => child.value || child.children[0].value).join("");
+};
+
+const transformParagraph = node => {
+  let text = "";
+  text += ASTERISK_WITH_SPACES;
+  const childrenText = getParagraphChildrenText(node);
+
+  if (hasLineBreaks(childrenText)) {
+    text += addLeadingCommentForTextWithLineBreaks({
+      text: childrenText,
+      addCommentForFirstItem: false,
+    });
+  } else {
+    text += childrenText;
+  }
+  text += DOUBLE_LINE_BREAK_WITH_LEADING_COMMENT;
+
+  return text;
+};
+
+const transformImg = node => {
+  const { src, alt } = parseImgTag(node.value);
+  let text = ASTERISK_WITH_SPACES;
+  text += `![${alt}](${src}|height=${JSDOC_IMG_HEIGHT}|width=${JSDOC_IMG_WIDTH})`;
+  text += DOUBLE_LINE_BREAK_WITH_LEADING_COMMENT;
+
+  return text;
+};
+
+const transformNodesToText = nodes => {
+  let text = DOUBLE_LINE_BREAK_WITH_LEADING_COMMENT;
+
+  nodes.forEach(node => {
+    if (matches(CODE_PATTERN, node)) {
+      text += transformCode(node);
+    } else if (matches(IMG_PATTERN, node)) {
+      text += transformImg(node);
+    } else if (matches(PARAGRAPH_PATTERN, node)) {
+      text += transformParagraph(node);
+    }
+  });
+
+  return addLeadingComment(text, true);
+};
+
+const parseImgTag = imgTagStr =>
+  imgTagStr.split(" ").reduce((acc, item) => {
+    let [attrName, attrValue] = item.split("=");
+    attrValue = attrValue?.replaceAll(">", "").replaceAll('"', "");
+
+    return mergeLeft({ [attrName]: attrValue }, acc);
+  }, {});
+
+const removeCommentTags = str => str.replaceAll("/*", "").replaceAll("*/", "");
+
+export const parseTypeFile = typeFileContent =>
+  babelParser.parse(typeFileContent, {
+    sourceType: "module",
+    plugins: [["typescript", { dts: true }]],
+  });
+
+export const buildEntityTitleToEntityDescMap = (nodes, map) => {
+  nodes.forEach((node, idx) => {
+    if (!matches(SUBHEADING_PATTERN, node)) return;
+
+    const entityName = removeSpaces(node.children[0].value);
+    const entityRightSiblings = [];
+
+    for (let i = idx + 1; i < nodes.length; i++) {
+      const siblingNode = nodes[i];
+
+      if (matches(HTML_EXCEPT_IMG_PATTERN, siblingNode)) continue;
+
+      if (matches(SUBHEADING_PATTERN, siblingNode)) break;
+
+      entityRightSiblings.push(siblingNode);
+    }
+    const entityRightSiblingsText = transformNodesToText(entityRightSiblings);
+    map[entityName] = entityRightSiblingsText;
+  });
+};
+
+export const defaultTypeFileTraverser = ({
+  typeFileAST,
+  typeFileName,
+  entityTitleToDescMapOfAllFiles,
+}) =>
+  traverse(typeFileAST, {
+    ExportNamedDeclaration: ({ node }) => {
+      const entityName = findEntityName(node);
+      const entityDesc = entityTitleToDescMapOfAllFiles[entityName];
+
+      if (!entityName || !entityDesc) {
+        return;
+      }
+
+      babelTypes.addComment(node, "leading", entityDesc);
+
+      const { code } = generate(typeFileAST, {});
+
+      fs.writeFileSync(path.resolve(typeFileName), code);
+    },
+  });
+
+export const syncTypeFiles = exportedTypesFolderName => {
+  const sourceDir = path.resolve(TYPES_FOLDER_NAME);
+  const destDir = path.resolve(exportedTypesFolderName);
+
+  fs.cpSync(sourceDir, destDir, { recursive: true });
+};
+
+export const getFileNameList = dirPath => {
+  let files = [];
+  const items = fs.readdirSync(dirPath, { withFileTypes: true });
+
+  for (const item of items) {
+    if (item.isDirectory()) {
+      files = [...files, ...getFileNameList(path.join(dirPath, item.name))];
+    } else {
+      files.push(path.join(dirPath, item.name));
+    }
+  }
+
+  return files;
+};
+
+export const getFileContent = fileName =>
+  fs.readFileSync(path.resolve(fileName), "utf8").toString();
+
+export const parseMarkdown = fileContent =>
+  unified().use(remarkParse).parse(fileContent);
+
+export const findEntityName = node =>
+  node?.declaration?.declarations?.[0]?.id?.name || node?.declaration?.id?.name;
+
+export const matchesAny = curry((list, obj) => list.some(matches(__, obj)));

package/configs/webpack/index.js

@@ -35,6 +35,7 @@ const commonOptions = {
       silent: true,
     }),
   ],
+  ignoreWarnings: [/Failed to parse source map/],
 };
 
 // This rule is causing issues to react-svg-loader

package/cypress-utils.d.ts

@@ -1,4 +1,4 @@
-// selecotrs ------------------------------------------------
+// selectors ------------------------------------------------
 
 type CommonSelectors = {
   alertTitle: string;
@@ -32,7 +32,6 @@ type CommonSelectors = {
   tabItem: (index: string) => string;
   dropdownWrapper: (index: string) => string;
 };
-
 type MemberSelectors = {
   activatedMembersButton: string;
   columnCheckBox: string;
@@ -48,7 +47,6 @@ type MemberSelectors = {
   searchTextField: string;
   submitButton: string;
 };
-
 type LoginSelectors = {
   appleAuthenticationButton: string;
   emailTextField: string;
@@ -61,13 +59,11 @@ type LoginSelectors = {
   submitButton: string;
   twitterAuthenticationButton: string;
 };
-
 type ProfileSelectors = {
   tab: string;
   logoutLink: string;
   profileOptionsContainer: string;
 };
-
 type SignUpSelectors = {
   emailTextField: string;
   firstNameTextField: string;
@@ -108,7 +104,6 @@ type CommonTexts = {
   unsavedChangesAlertMessage: string;
   unsavedChangesAlertTitle: string;
 };
-
 type MemberText = {
   addMember: string;
   admin: string;
@@ -129,7 +124,6 @@ type MemberText = {
   newHeading: string;
   updatedMemberRole: string;
 };
-
 type MemberTableTexts = {
   created: string;
   email: string;
@@ -137,13 +131,11 @@ type MemberTableTexts = {
   role: string;
   teams: string;
 };
-
 type SignUpTexts = {
   email: string;
   profile: string;
   tryItFree: string;
 };
-
 type Environment = {
   development: string;
   staging: string;
@@ -151,29 +143,11 @@ type Environment = {
 
 // utils ------------------------------------------------
 
-// Utils: auth
-
-function verifySSOLoginPage(): Void;
-
-function logout(homeUrl: string): Void;
-
-// Utils: date
-
-function currentDate(): String;
-
-function futureDate(numberOfDays: number = 1): String;
-
-function pastDate(numberOfDays: number = 1): String;
-
 // Utils: common
-export function initCustomCommands(): Void;
-
-export function dataCy(dataCyId: string): String;
-
-export function getTestTitle(): String;
-
-export function getUrl(path: string): String;
-
+export function initCustomCommands(): void;
+export function dataCy(dataCyId: string): string;
+export function getTestTitle(): string;
+export function getUrl(path: string): string;
 export function initializeCredentials(props: {
   businessName: string;
   currentUserName: string;
@@ -183,13 +157,23 @@ export function initializeCredentials(props: {
   domain: string;
   subdomainName: string;
   skipSetup: boolean;
-}): String;
-
-export function joinHyphenCase(string: string | string[]): String;
-
-export function setListCount(countSelector: string, alias: string): Void;
-
-export function verifyListCount(countSelector: string, count: number): String;
+}): string;
+/**
+ *
+ * Curried: false
+ *
+ * This function joins the given strings with hyphen.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * joinHyphenCase("hello", "world"); // output: "hello-world"
+ * @endexample
+*/
+export function joinHyphenCase(string: string | string[]): string;
+export function setListCount(countSelector: string, alias: string): void;
+export function verifyListCount(countSelector: string, count: number): string;
 
 // Utils: organization
 export function createOrganization(props: {
@@ -199,91 +183,103 @@ export function createOrganization(props: {
   firstName: string;
   lastName: string;
   subdomainName: string;
-}): Void;
+}): void;
 
 // Utils: validation
+export function verifyCrossSiteScript(inputSelector: string, submitSelector: string): void;
 
-export function verifyCrossSiteScript(
-  inputSelector: string,
-  submitSelector: string
-): Void;
-
-// Utils: members
-
-function addMemberViaRequest(props: {
+// exporting all utils
+export const authUtils: {
+  verifySSOLoginPage: () => void;
+  logout: (homeUrl: string) => void;
+};
+/**
+ *
+ * Utils related to the date
+ *
+ * Import statement
+ *
+ * @example 
+ *
+ * import { dateUtils } from "@bigbinary/neeto-commons-frontend/cypress-utils";
+ * @endexample
+ * Function to get the current date in YYYY-MM-DD format.
+ *
+ * @example 
+ *
+ * dateUtils.currentDate();
+ * @endexample
+ * Function to return the date after n days from the current date.
+ *
+ * @example 
+ *
+ * // Current date is 2023-02-07
+ * dateUtils.futureDate(2); // return 2023-02-09
+ * @endexample
+ * Function to return the date before n days from the current date.
+ *
+ * @example 
+ *
+ * // Current date is 2023-02-07
+ * dateUtils.pastDate(2); // return 2023-02-05
+ * @endexample
+*/
+export const dateUtils: {
+  currentDate: () => string;
+  futureDate: (numberOfDays: number) => string;
+  pastDate: (numberOfDays: number) => string;
+};
+type AddMemberViaRequestPropsType = {
   email: string;
   role: string;
   requestCount: number;
   appName: string;
-}): Void;
-
-function addMemberViaUI(email: string, role: string = "Agent"): Void;
-
-function activateMember(props: {
+};
+type ActivateMembersPropsType = {
   email: string;
   skipSearchRequest: boolean;
-}): Void;
-
-function activateMemberViaRequest(email: string, requestCount: number): Void;
-
-function checkColumnCheckBox(fieldSelector: string): Void;
-
-function deactivateMember(props: {
+};
+type UpdateMembersPropsType = {
   email: string;
+  role: string;
   skipSearchRequest: boolean;
-}): Void;
-
-function deactivateMemberViaRequest(email: string, requestCount: number): Void;
-
-function updateMemberRole(props: {
+};
+type VerifyMembersPropsType = {
   email: string;
   role: string;
   skipSearchRequest: boolean;
-}): Void;
-
-function interceptMemberApi(alias: string, times: number = 1): Void;
-
-function navigateToMembersPage(waitForRequest: boolean = true): Void;
-
-function unCheckColumnCheckBox(fieldSelector: string): Void;
-
-function verifyMemberDetails(props: {
+};
+type DeactivateMembersPropsType = {
   email: string;
-  role: string;
   skipSearchRequest: boolean;
-}): Void;
-
-// exporting all utils
-
-export const authUtils = { verifySSOLoginPage, logout };
-export const dateUtils = { currentDate, futureDate, pastDate };
-export const memberUtils = {
-  addMemberViaRequest,
-  addMemberViaUI,
-  activateMember,
-  checkColumnCheckBox,
-  deactivateMember,
-  deactivateMemberViaRequest,
-  updateMemberRole,
-  interceptMemberApi,
-  navigateToMembersPage,
-  unCheckColumnCheckBox,
-  verifyMemberDetails,
+};
+export const memberUtils: {
+  addMemberViaRequest: (props: AddMemberViaRequestPropsType) => void;
+  addMemberViaUI: (email: string, role: string) => void;
+  activateMember: (props: ActivateMembersPropsType) => void;
+  deactivateMember: (props: DeactivateMembersPropsType) => void;
+  checkColumnCheckBox: (fieldSelector: string) => void;
+  deactivateMemberViaRequest: (email: string, requestCount: number) => void;
+  updateMemberRole: (props: UpdateMembersPropsType) => void;
+  interceptMemberApi: (alias: string, times: number) => void;
+  navigateToMembersPage: (waitForRequest: boolean) => void;
+  unCheckColumnCheckBox: (fieldSelector: string) => void;
+  verifyMemberDetails: (props: VerifyMembersPropsType) => void;
 };
 
 // exporting all selectors
 
-export declare const commonSelectors: CommonSelectors;
-export declare const memberSelectors: MemberSelectors;
-export declare const loginSelectors: LoginSelectors;
-export declare const profileSelectors: ProfileSelectors;
-export declare const signUpSelectors: SignUpSelectors;
+export const commonSelectors: CommonSelectors;
+export const memberSelectors: MemberSelectors;
+export const loginSelectors: LoginSelectors;
+export const profileSelectors: ProfileSelectors;
+export const signUpSelectors: SignUpSelectors;
 
 // exporting all texts
 
-export declare const commonTexts: CommonTexts;
-export declare const memberTexts: MemberText;
-export declare const memberTableTexts: MemberTableTexts;
-export declare const signUpTexts: SignUpTexts;
-export declare const environment: Environment;
-export declare const isStagingEnv: Boolean;
+export const commonTexts: CommonTexts;
+export const memberTexts: MemberText;
+export const memberTableTexts: MemberTableTexts;
+export const signUpTexts: SignUpTexts;
+export const environment: Environment;
+export const isStagingEnv: boolean;

package/initializers.d.ts

@@ -1,7 +1,10 @@
 type Skippable<T> = boolean | Partial<T>;
-
 type Configurations = {
-  translationResources?: { en: { translation: object } };
+  translationResources?: {
+    en: {
+      translation: object;
+    };
+  };
   skip?: Partial<{
     globalProps: boolean;
     mixpanel: boolean;
@@ -26,7 +29,6 @@ type Configurations = {
     }>;
   }>;
 };
-
 type GlobalPropsType = {
   railsEnv: string;
   honeybadgerApiKey: string;
@@ -56,12 +58,21 @@ type GlobalPropsType = {
   permissions: string[];
   [key: string]: any;
 };
-
-export default function initializeApplication(
-  configurations: Configurations
-): void;
-
+export default function initializeApplication(configurations: Configurations): void;
 export const globalProps: GlobalPropsType;
 
 /** @deprecated use useDisplayErrorPage from react-utils bundle */
-export function useDisplayErrorPage(): Boolean;
+/**
+ *
+ * This hook will return true if any API request fails with 404 or 403 status.
+ *
+ * Until any such API response is received, it will return false. It can be used
+ *
+ * to render ErrorPage conditionally. Refer:
+ *
+ * axios error response handler
+ *
+ * for more details.
+ *
+*/
+export function useDisplayErrorPage(): Boolean;