feat(jsdoc): add JSDoc comments (#83)

* docs(jsdoc): add JSDoc comments

Add JSDoc comments for generateEmail utility

Resolves #61

Signed-off-by: Niloy Sikdar <niloysikdar30@gmail.com>

* docs(jsdoc): add comments for generateTextEmail

Add JSDoc comments for generateTextEmail utility

Resolves #61

Signed-off-by: Niloy Sikdar <niloysikdar30@gmail.com>

* docs(jsdoc): add comments for generateTextEmailFromHTML

Add JSDoc comments for genearteTextEmailFromHTML utility

Resolves #61

Signed-off-by: Niloy Sikdar <niloysikdar30@gmail.com>

* docs(jsdoc): add comments for sx and makeStyles

Add JSDoc comments for sx and makeStyles utilities

re #61

Signed-off-by: Niloy Sikdar <niloysikdar30@gmail.com>

* docs(jsdoc): add comment for BaseStyleProp

Add JSDoc comments for BaseStyleProp interface

re #61

Signed-off-by: Niloy Sikdar <niloysikdar30@gmail.com>

* docs(jsdoc): add comments for Typography

Add JSDoc comments for Typography component

re #61

Signed-off-by: Niloy Sikdar <niloysikdar30@gmail.com>

* docs(jsdoc): add comments for components

Add JSDoc comments for all of the components

re #61

Signed-off-by: Niloy Sikdar <niloysikdar30@gmail.com>

* feat(typedoc): add typedoc generate config and scripts

Add typedocOptions inside tsconfig and add build script to generate typedoc site

Resolves #61

Signed-off-by: Niloy Sikdar <niloysikdar30@gmail.com>

Signed-off-by: Niloy Sikdar <niloysikdar30@gmail.com>

package.json

@@ -37,7 +37,8 @@
     "lint-staged": "lint-staged",
     "release": "semantic-release --branches main",
     "storybook": "start-storybook -p 6006",
-    "build-storybook": "build-storybook -o docs-build"
+    "build:storybook": "build-storybook -o storybook",
+    "build:typedoc": "typedoc"
   },
   "lint-staged": {
     "src/**": [
@@ -93,6 +94,7 @@
     "react-dom": "^18.2.0",
     "react-test-renderer": "^18.2.0",
     "semantic-release": "^19.0.3",
+    "typedoc": "^0.23.10",
     "typescript": "^4.7.3"
   },
   "husky": {

src/components/Button/Button.tsx

@@ -5,10 +5,28 @@ import { sx } from '../../utils/sx';
 
 type ButtonStyles = 'root' | 'primary' | 'secondary';
 
+/**
+ * Interface for PropTypes for the `Button` component.
+ */
 export interface ButtonProps extends BaseStyleProp<ButtonStyles> {
+  /**
+   * The content of the component.
+   */
   children?: ReactNode;
+  /**
+   * Applies the theme button styles.
+   * @default 'primary'
+   */
   variant?: 'primary' | 'secondary';
+  /**
+   * The URL to link to when the button is clicked.
+   * An `a` element will be used as the root node.
+   */
   href: string;
+  /**
+   * The target of the link.
+   * @default '_blank'
+   */
   target?: HTMLAttributeAnchorTarget;
 }
 

src/components/Column/Column.tsx

@@ -5,9 +5,23 @@ import { BaseStyleProp } from '../types';
 
 type ColumnStyles = 'root';
 
+/**
+ * Interface for PropTypes for the `Column` component.
+ */
 export interface ColumnProps extends BaseStyleProp<ColumnStyles> {
+  /**
+   * The content of the component.
+   */
   children?: ReactNode;
+  /**
+   * The alignment of the children.
+   * @default 'center'
+   */
   align?: 'left' | 'center' | 'right';
+  /**
+   * The vertical alignment of the children.
+   * @default 'top'
+   */
   verticalAlign?: CSSProperties['verticalAlign'];
 }
 

src/components/Divider/Divider.tsx

@@ -5,11 +5,33 @@ import { BaseStyleProp } from '../types';
 
 type DividerStyles = 'root';
 
+/**
+ * Interface for PropTypes for the `Divider` component.
+ */
 export interface DividerProps extends BaseStyleProp<DividerStyles> {
+  /**
+   * The alignment of the divider.
+   * @default 'left'
+   */
   align?: 'left' | 'center' | 'right';
+  /**
+   * The color of the divider.
+   */
   color?: CSSProperties['borderColor'];
+  /**
+   * The type of the divider.
+   * @default 'solid'
+   */
   type?: CSSProperties['borderStyle'];
+  /**
+   * The thickness of the divider.
+   * @default '1px'
+   */
   size?: CSSProperties['borderWidth'];
+  /**
+   * The width of the divider.
+   * @default '100%'
+   */
   width?: CSSProperties['width'];
 }
 

src/components/Email/Email.tsx

@@ -4,7 +4,13 @@ import { makeStyles } from '../../utils/makeStyles';
 
 type EmailStyles = 'root';
 
+/**
+ * Interface for PropTypes for the `Email` component.
+ */
 export interface EmailProps extends BaseStyleProp<EmailStyles> {
+  /**
+   * The content of the component.
+   */
   children?: ReactNode;
 }
 

src/components/Image/Image.tsx

@@ -13,12 +13,35 @@ type ImageStyles =
   | 'captionSection'
   | 'imageColumn';
 
+/**
+ * Interface for PropTypes for the `Image` component.
+ */
 export interface ImageProps extends BaseStyleProp<ImageStyles> {
+  /**
+   * The URL or filepath of the image.
+   */
   src: string;
+  /**
+   * The alt text for the image.
+   */
   alt: string;
+  /**
+   * The caption for the image.
+   */
   caption?: string;
+  /**
+   * The width of the image.
+   */
   width: CSSProperties['width'];
+  /**
+   * The height of the image.
+   * @default 'auto'
+   */
   height?: CSSProperties['height'];
+  /**
+   * The alignment of the caption.
+   * @default 'center'
+   */
   captionAlign?: 'left' | 'center' | 'right';
 }
 

src/components/Link/Link.tsx

@@ -4,9 +4,22 @@ import { makeStyles } from '../../utils/makeStyles';
 
 type LinkStyles = 'root';
 
+/**
+ * Interface for PropTypes for the `Link` component.
+ */
 export interface LinkProps extends BaseStyleProp<LinkStyles> {
+  /**
+   * The content of the component.
+   */
   children?: ReactNode;
+  /**
+   * The URL to link to.
+   */
   href: string;
+  /**
+   * The target of the link.
+   * @default '_blank'
+   */
   target?: HTMLAttributeAnchorTarget;
 }
 

src/components/Preheader/Preheader.tsx

@@ -3,7 +3,13 @@ import { BaseStyleProp } from '../types';
 
 type PreheaderStyles = 'root';
 
+/**
+ * Interface for PropTypes for the `Preheader` component.
+ */
 export interface PreheaderProps extends BaseStyleProp<PreheaderStyles> {
+  /**
+   * The text for the preheader.
+   */
   text: string;
 }
 

src/components/Quote/Quote.stories.tsx

@@ -1,4 +1,3 @@
-import React from 'react';
 import { ComponentStory, ComponentMeta } from '@storybook/react';
 
 import { Quote } from './Quote';

src/components/Quote/Quote.tsx

@@ -4,7 +4,13 @@ import { BaseStyleProp } from '../types';
 
 type QuoteStyles = 'root';
 
+/**
+ * Interface for PropTypes for the `Quote` component.
+ */
 export interface QuoteProps extends BaseStyleProp<QuoteStyles> {
+  /**
+   * The content of the component.
+   */
   children?: ReactNode;
 }
 

src/components/Section/Section.tsx

@@ -5,8 +5,18 @@ import { BaseStyleProp } from '../types';
 
 type SectionStyles = 'root' | 'body' | 'row';
 
+/**
+ * Interface for PropTypes for the `Section` component.
+ */
 export interface SectionProps extends BaseStyleProp<SectionStyles> {
+  /**
+   * The content of the component.
+   */
   children?: ReactNode;
+  /**
+   * If `true`, the `section` will take up the full width of its container.
+   * @default true
+   */
   fullWidth?: boolean;
 }
 

src/components/Typography/Typography.tsx

@@ -5,8 +5,18 @@ import { sx } from '../../utils/sx';
 
 type ButtonStyles = 'root';
 
+/**
+ * Interface for PropTypes for the `Typography` component.
+ */
 export interface TypographyProps extends BaseStyleProp<ButtonStyles> {
+  /**
+   * The content of the component.
+   */
   children: ReactNode;
+  /**
+   * Applies the theme typography styles.
+   * @default 'body1'
+   */
   variant?:
     | 'h1'
     | 'h2'
@@ -19,6 +29,10 @@ export interface TypographyProps extends BaseStyleProp<ButtonStyles> {
     | 'body1'
     | 'body2'
     | 'caption';
+  /**
+   * Set the text-align on the component.
+   * @default 'left'
+   */
   align?: CSSProperties['textAlign'];
 }
 

src/components/types/index.ts

@@ -1,6 +1,12 @@
 import { CSSProperties } from 'react';
 
 export interface BaseStyleProp<T extends string> {
+  /**
+   * Override or extend the styles applied to the component.
+   */
   classes?: Partial<Record<T, CSSProperties>>;
+  /**
+   * The class name to be applied to the element.
+   */
   className?: string;
 }

src/utils/generateEmail/generateEmail.ts

@@ -2,13 +2,40 @@ import ReactDOMServer from 'react-dom/server';
 import fs from 'fs';
 import { deafultHTML } from './defaultHTML';
 
+/** An optional configuration object for `generateEmail` */
 interface GenerateEmailOptions {
+  /** HTML file path to override the base HTML. */
   baseTemplate?: string;
+  /** CSS file path to override the base CSS styles. */
   baseStyles?: string;
+  /**
+   * Placeholder text to replace the base CSS styles.
+   * @default 'EMAIL_BASE_STYLES'
+   */
   baseStylesReplacementString?: string;
+  /**
+   * Placeholder text to replace the email body.
+   * @default 'EMAIL_BODY_CONTENT'
+   */
   baseBodyReplacementString?: string;
 }
 
+/**
+ * Function to convert React Email Layouts to HTML.
+ * @param {React.ReactElement}  jsxElement - React email layout which needs to be converted.
+ * @param {Object} [options] - An optional param options for the additional configurations.
+ * @param {string} [options.baseTemplate] - HTML file path to override the base HTML.
+ * @param {string} [options.baseStyles] - CSS file path to override the base CSS styles.
+ * @param {string} [options.baseStylesReplacementString='EMAIL_BASE_STYLES'] - Placeholder text to replace the base CSS styles.
+ * @param {string} [options.baseBodyReplacementString='EMAIL_BODY_CONTENT'] - Placeholder text to replace the email body.
+ * @returns {string} HTML version of the email in string format.
+ * @example
+ * import { generateEmail } from '@leopardslab/react-email';
+ * import { EmailLayout } from './EmailLayout';
+ * const html = generateEmail(EmailLayout());
+ * console.log(html);
+ */
+
 export const generateEmail = (
   jsxElement: React.ReactElement,
   options?: GenerateEmailOptions,

src/utils/generateTextEmail/generateTextEmail.ts

@@ -1,6 +1,17 @@
 import { generateEmail } from '../generateEmail';
 import { generateTextEmailFromHTML } from '../generateTextEmailFromHTML';
 
+/**
+ * Function to convert React Email Layouts to Text version.
+ * @param {JSX.Element}  jsxElement - React email layout which needs to be converted.
+ * @returns {string} Text version of the email in string format.
+ * @example
+ * import { generateTextEmail } from '@leopardslab/react-email';
+ * import { EmailLayout } from './EmailLayout';
+ * const text = generateTextEmail(EmailLayout());
+ * console.log(text);
+ */
+
 export const generateTextEmail = (jsxElement: JSX.Element): string => {
   const HTML = generateEmail(jsxElement);
   const plainText = generateTextEmailFromHTML(HTML);

src/utils/generateTextEmailFromHTML/generateTextEmailFromHTML.ts

@@ -15,6 +15,12 @@ const headingFormatter =
     builder.closeBlock({ trailingLineBreaks: formatOptions.trailingLineBreaks || 1 });
   };
 
+/**
+ * Function to convert HTML Email to Text version.
+ * @param {string}  html - HTML which needs to be converted.
+ * @returns {string} Text version of the email in string format.
+ */
+
 export const generateTextEmailFromHTML = (html: string): string => {
   const plainText = convert(html, {
     formatters: {

src/utils/makeStyles/makeStyles.ts

@@ -19,6 +19,12 @@ const mergeStyles = (originalClasses: CSSClasses, overrideClasses: CSSClasses):
   return newClasses;
 };
 
+/**
+ * Function which revokes a hook to combine and merge classes.
+ * @param classes - The classes to be merged with the override classes
+ * @returns The `useStyles` hook to combine and merge classes.
+ */
+
 export const makeStyles = (classes: CSSClasses) => {
   return (options?: overrideOptions) => {
     const overrideClasses = options?.classes;

src/utils/sx/sx.ts

@@ -2,6 +2,12 @@ import { CSSProperties } from 'react';
 
 type SXProps = CSSProperties | false | undefined;
 
+/**
+ * Function to merge CSSProperties.
+ * @param args - The CSSProperties to be merged with the override CSSProperties
+ * @returns The merged CSSProperties.
+ */
+
 export const sx = (...args: SXProps[]): CSSProperties => {
   const initialValue: CSSProperties = {};
 

tsconfig.json

@@ -25,6 +25,10 @@
     "jsx": "react-jsx",
     "pretty": true
   },
+  "typedocOptions": {
+    "entryPoints": ["./src/"],
+    "out": "typedoc"
+  },
   "include": ["src/**/*"],
   "exclude": ["node_modules"]
 }