@digi-frontend/dgate-api-documentation 1.2.0 → 1.3.0

package/src/components/table/tags-table.tsx

@@ -0,0 +1,348 @@
+import { useEffect, useState } from 'react'
+import './style.scss'
+import _styles from '../InfoForm/InfoForm.module.scss'
+import { Button, Input, TextArea } from 'digitinary-ui'
+import Tooltip from '../Tooltip/Tooltip'
+import SVGLoader from '../SVGLoader/SVGLoader'
+import { AddRow, EditIcon, DeleteIcon } from '../../assets/icons'
+import styles from '../MethodAccordion/MethodAccordion.module.scss'
+import { useFormik } from 'formik'
+import * as yup from 'yup'
+import regex from '../../constants/regex'
+
+const TagsTable = ({ id, headCells, data, isFormOpen, setIsFormOpen, saveNewRow, readOnly }) => {
+  const [text, setText] = useState('')
+  const [externalDesc, setExternalDesc] = useState('')
+  const [externalUrl, setExternalUrl] = useState('')
+  const [tooltipRef, setTooltipRef] = useState(null)
+  const [externalTooltipRefs, setExternalTooltipRefs] = useState(null)
+  const { values, errors, setFieldValue, isValid, submitForm, resetForm,dirty } = useFormik({
+    validateOnMount: true,
+    initialValues: {
+      name: '',
+      description: '',
+      externalDocs: {
+        url: '',
+        description: '',
+      },
+    },
+    validationSchema: yup.object().shape({
+      name: yup.string().trim().required('Tag name is required'),
+      description: yup.string().optional(),
+      externalDocs: yup
+        .object()
+        .shape({
+          url: yup
+            .string()
+            .trim()
+            .matches(regex.urlRegex, 'Invalid URL')
+            .when('description', (description, schema) => {
+              return description?.at(0)
+                ? schema.required('URL is required when description is provided')
+                : schema.optional()
+            }),
+          description: yup.string().trim().optional(),
+        })
+        .optional(),
+    }),
+    onSubmit: (values) => {
+      saveNewRow(values)
+      setText('')
+      resetForm()
+      setIsFormOpen(false)
+    },
+    validateOnChange: true,
+  })
+
+  return (
+    <div className="tableSectionContainer">
+      <div className="tableContainer">
+        <table id={id || ''} className={`table borderRadiusTop borderRadiusBottom`}>
+          <thead className="tableHead">
+            <tr>
+              {headCells?.map((headCell) => (
+                <th
+                  key={headCell.id}
+                  className={`tableHeadCell ${headCell.classes || ''}`}
+                  style={{ width: headCell.width, minWidth: headCell.minWidth }}
+                >
+                  <div
+                    className="headContainer"
+                    data-id={`${
+                      typeof headCell.label === 'string'
+                        ? headCell.label.toUpperCase().replace(/[^a-zA-Z0-9]+/g, '_')
+                        : 'UNKNOWN_LABEL'
+                    }_COLUMN`}
+                  >
+                    {headCell.label}
+                  </div>
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody className="tableBody" data-id="TABLE_BODY">
+            {data?.map((row, rowIndex) => {
+              return (
+                <tr key={rowIndex} data-i={rowIndex} className={`row`}>
+                  {headCells?.map((headCell) => {
+                    const cellContent = row[headCell.id] !== '_' && (
+                      <div
+                        data-id="TEXT_DESCRIPTION"
+                        className="tableData"
+                        style={{
+                          width: headCell.width,
+                          minWidth: headCell.minWidth,
+                        }}
+                      >
+                        {row[headCell.id]}
+                      </div>
+                    )
+
+                    return (
+                      <td
+                        key={headCell.id}
+                        style={{
+                          width: headCell.width,
+                          minWidth: headCell.minWidth,
+                        }}
+                      >
+                        {cellContent}
+                      </td>
+                    )
+                  })}
+                </tr>
+              )
+            })}
+            {isFormOpen ? (
+              <tr key={''} data-i={''} className={`row`}>
+                <td key={'tag name'}>
+                  <div data-id="TEXT_DESCRIPTION" className="tableData">
+                    <Input
+                      placeholder="Tag name"
+                      size="large"
+                      type="text"
+                      maxLength={25}
+                      onChange={(value) => {
+                        !regex.basic.test(value) && setFieldValue('name', value)
+                      }} // Pass the value directly
+                      value={values.name} // Bind value to the state
+                      disabled={readOnly}
+                    />
+                  </div>
+                </td>
+
+                <td key={'tagDescRequired'}>
+                  <div data-id="TEXT_DESCRIPTION" className="tableData">
+                    <div className={styles.paramDescContainer}>
+                      <Tooltip
+                        arrowWithBorder
+                        placement="bottom-end"
+                        type="function"
+                        trigger="click"
+                        delay={[0, 0]}
+                        onCreate={(instance) => setTooltipRef(instance)}
+                        onShow={() => {
+                          setText(values.description || '') // Reset to current value when shown
+                        }}
+                        onHidden={() => {
+                          setText(values.description || '') // Reset on close
+                        }}
+                        content={
+                          <div className={_styles.editDescTooltipContent}>
+                            <p className={_styles.editDescTooltipContent_header}>Description</p>
+                            <TextArea
+                              value={text || values.description}
+                              disabled={readOnly}
+                              maxLength={25}
+                              placeholder="Describe Tag..."
+                              onChange={(value) => {
+                                if (value === '' || regex.ASCII.test(value)) setText(value)
+                              }}
+                            />
+                            {!readOnly && (
+                              <Button
+                                className={_styles.editDescTooltipContent_btn}
+                                variant="outlined"
+                                size="small"
+                                onClick={() => {
+                                  setFieldValue('description', text?.trim())
+                                  tooltipRef?.hide()
+                                }}
+                                disabled={!(text || values.description)?.trim()}
+                              >
+                                Apply
+                              </Button>
+                            )}
+                          </div>
+                        }
+                      >
+                        <Button
+                          className={_styles.editDescBtn}
+                          style={{ paddingLeft: 0 }}
+                          variant="link"
+                          color="action"
+                          endIcon={<SVGLoader src={EditIcon} width="1.5rem" height="1.5rem" />}
+                        >
+                          {readOnly ? 'View ' : 'Add '} Description
+                        </Button>
+                      </Tooltip>
+                    </div>{' '}
+                  </div>
+                </td>
+                <td key={'tagExternal'}>
+                  <div className="tableData">
+                    <div className={_styles.paramDescContainer}>
+                      <Tooltip
+                        arrowWithBorder
+                        placement="bottom-end"
+                        type="function"
+                        trigger="click"
+                        delay={[0, 0]}
+                        onCreate={(instance) => setExternalTooltipRefs(instance)}
+                        onShow={() => {
+                          setExternalDesc(values.externalDocs.description || '')
+                          setExternalUrl(values.externalDocs.url || '')
+                        }}
+                        onHidden={() => {
+                          setExternalDesc(values.externalDocs.description || '')
+                          setExternalUrl(values.externalDocs.url || '')
+                        }}
+                        content={
+                          <div className={_styles.editDescTooltipContent}>
+                            <p className={_styles.editDescTooltipContent_header}>
+                              External Docs Description
+                            </p>
+                            <TextArea
+                              placeholder="Describe External Doc..."
+                              value={externalDesc || values.externalDocs.description}
+                              disabled={readOnly}
+                              maxLength={25}
+                              onChange={(value) => {
+                                if (value === '' || regex.ASCII.test(value)) setExternalDesc(value)
+                              }}
+                            />
+                            <p className={_styles.editDescTooltipContent_header}>
+                              External Docs Link
+                            </p>
+                            <TextArea
+                              placeholder="External Docs Link..."
+                              restrictedCharsRegex={regex.urlRegex}
+                              value={externalUrl || values.externalDocs.url}
+                              disabled={readOnly}
+                              maxLength={200}
+                              onChange={(value) => {
+                                if (value === '' || regex.ASCII.test(value)) setExternalUrl(value)
+                              }}
+                            />
+                            {!readOnly && (
+                              <Button
+                                className={_styles.editDescTooltipContent_btn}
+                                variant="outlined"
+                                size="small"
+                                onClick={() => {
+                                  setFieldValue(`externalDocs`, {
+                                    description: externalDesc,
+                                    url: externalUrl,
+                                  })
+
+                                  externalTooltipRefs?.hide()
+                                }}
+                                disabled={
+                                  !(externalUrl || values.externalDocs.url)?.trim() ||
+                                  !regex.urlRegex.test(externalUrl || values.externalDocs.url)
+                                }
+                              >
+                                Apply
+                              </Button>
+                            )}
+                          </div>
+                        }
+                      >
+                        {readOnly ? (
+                          <a
+                            className={_styles.editDescBtn}
+                            variant="link"
+                            color="action"
+                            href={values.externalDocs?.url}
+                            target="_blank"
+                          >
+                            {values?.externalDocs?.description
+                              ? values?.externalDocs?.description?.substring(0, 12)
+                              : '-'}
+                            {values?.externalDocs?.description &&
+                            values?.externalDocs?.description?.length > 12
+                              ? '...'
+                              : ''}
+                          </a>
+                        ) : (
+                          <Button
+                            className={_styles.editDescBtn}
+                            variant="link"
+                            color="action"
+                            endIcon={<SVGLoader src={EditIcon} width="1.5rem" height="1.5rem" />}
+                          >
+                            {readOnly ? 'View ' : 'Add '} External Docs Link
+                          </Button>
+                        )}
+                      </Tooltip>
+                      <div className={_styles.paramDescContainer_separator}></div>
+                      {!readOnly && (
+                        <Button
+                          className={_styles.deleteParamBtn}
+                          variant="link"
+                          color="error"
+                          endIcon={
+                            <SVGLoader src={DeleteIcon} width="1.125rem" height="1.125rem" />
+                          }
+                          onClick={() => {
+                            resetForm()
+                            setText('')
+                            setIsFormOpen(false)
+                          }} // Correctly delete the new row
+                        />
+                      )}
+
+                      {!readOnly && (
+                        <Button
+                          className={_styles.deleteParamBtn}
+                          variant="link"
+                          color="success"
+                          disabled={!isValid || !dirty}
+                          endIcon={<SVGLoader src={AddRow} width="0.125rem" height="0.125rem" />}
+                          onClick={() => {
+                            setText('')
+                            submitForm()
+                          }} // Save the new row when clicked
+                        />
+                      )}
+                    </div>
+                  </div>
+                </td>
+              </tr>
+            ) : (
+              <>
+                {!readOnly && (
+                  <tr key={'addNew'} data-i={'addNew'} className={`row`}>
+                    <td colSpan={5}>
+                      <Button
+                        variant="link"
+                        color="primary"
+                        onClick={() => {
+                          setIsFormOpen((prev) => !prev)
+                        }}
+                      >
+                        + Add Tag
+                      </Button>
+                    </td>
+                  </tr>
+                )}
+              </>
+            )}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  )
+}
+
+export default TagsTable

package/src/constants/index.ts

@@ -0,0 +1,95 @@
+export const methodColorMapping = {
+  get: {
+    label: 'Get',
+    color: '#3A6CD1',
+    order: 1,
+  },
+  post: {
+    label: 'Post',
+    color: '#3AAA35',
+    order: 2,
+  },
+  put: {
+    label: 'Put',
+    color: '#FAAD14',
+    order: 3,
+  },
+  delete: {
+    label: 'Delete',
+    color: '#DA3F3F',
+    order: 4,
+  },
+  patch: {
+    label: 'Patch',
+    color: '#58E2C2',
+    order: 5,
+  },
+  options: {
+    label: 'Options',
+    color: '#495D97',
+    order: 6,
+  },
+  trace: {
+    label: 'Trace',
+    color: '#FFA28F',
+    order: 7,
+  },
+  head: {
+    label: 'Head',
+    color: '#9461C9',
+    order: 8,
+  },
+}
+
+export const tagsTableHeaders = [
+  {
+    id: 'tagName',
+    label: 'Tag Name',
+    sortable: false,
+    classes: 'requiredParam',
+  },
+  {
+    id: 'description',
+    label: 'Description',
+    sortable: false,
+  },
+  {
+    id: 'externalDocs',
+    label: 'External Docs',
+    sortable: false,
+  },
+]
+
+export const paramsTableHeaders = [
+  {
+    id: 'paramName',
+    label: 'Parameter Name',
+    sortable: false,
+    required: true,
+    classes: 'requiredParam',
+  },
+  { id: 'paramType', label: 'In', sortable: false, classes: 'requiredParam' },
+  { id: 'schemaType', label: 'Schema-Type', sortable: false, classes: 'requiredParam' },
+  // { id: 'arraySchemaType', label: 'Array Schema Type', sortable: false },
+  { id: 'enum', label: 'Enum', sortable: false },
+  { id: 'required', label: 'Required', sortable: false, classes: 'requiredParam' },
+  { id: 'description', label: 'Description', sortable: false },
+]
+
+export const httpStatusCodes = [
+  // 1xx: Informational responses
+  100, 101, 102, 103,
+
+  // 2xx: Success
+  200, 201, 202, 203, 204, 205, 206, 207, 208, 226,
+
+  // 3xx: Redirection
+  300, 301, 302, 303, 304, 305, 306, 307, 308,
+
+  // 4xx: Client errors
+  400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418,
+  421, 422, 423, 424, 425, 426, 428, 429, 431, 451,
+
+  // 5xx: Server errors
+  500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511,
+]

package/src/constants/methods.constant.ts

@@ -0,0 +1,26 @@
+export type MethodOption = {
+  label: string
+  value: string
+  color: string
+}
+
+export const METHOD_OPTIONS: MethodOption[] = [
+  { label: 'Post', value: 'POST', color: '#10b981' },
+  { label: 'GET', value: 'GET', color: '#3b82f6' },
+  { label: 'Delete', value: 'DELETE', color: '#ef4444' },
+  { label: 'Put', value: 'PUT', color: '#f59e0b' },
+  { label: 'PATCH', value: 'PATCH', color: '#C0F4E8' },
+  { label: 'OPTIONS', value: 'OPTIONS', color: '#6b7280' },
+  { label: 'HEAD', value: 'HEAD', color: '#8b5cf6' },
+  { label: 'TRACE', value: 'TRACE', color: '#ec4899' },
+]
+
+export const METHOD_OPTIONS_CONFIG = [
+  {
+    list: METHOD_OPTIONS.map((method) => ({
+      labelConfig: { color: method.color, text: method.label },
+      value: method.value,
+      data: method,
+    })),
+  },
+]

package/src/constants/regex.ts

@@ -0,0 +1,7 @@
+const regex = {
+  basic: /[^a-zA-Z0-9-_ ]/, // not (alphanumeric + underscore + dash + space)
+  restrictNone: /^$/, // restrict nothing
+  ASCII: /^[\x00-\x7F]+$/,
+  urlRegex: /^(https?:\/\/|www\.)[a-zA-Z0-9-]+(\.[a-zA-Z]{2,})+(\/[^\s]*)?$/,
+}
+export default regex

package/src/context/SectionToggleContext.tsx

@@ -0,0 +1,121 @@
+import React, { createContext, useContext, useState, ReactNode, useMemo, useCallback } from 'react'
+
+export enum SectionEnum {
+  OVERVIEW = 'overview',
+  RESOURCE = 'resource',
+  API_SECTION = 'apiSection',
+  TAG_SECTION = 'tagSection',
+  ENDPOINTS_SECTION = 'endpointsSection',
+}
+
+type SectionKey =
+  | `api_${string}_${SectionEnum}`
+  | `api_${string}_${SectionEnum}_${string | number}`
+  | `api_${string}_${SectionEnum}_${string | number}_${string | number}`
+type ExpandedSections = Record<SectionKey, boolean>
+
+interface SectionToggleContextType {
+  expandedSections: ExpandedSections
+  toggleSection: (
+    apiId: string,
+    sections: ToggleSectionDescriptor[],
+    options?: ToggleOptions
+  ) => void
+  generateSectionKey: ({ apiId, type, index, id }: GenerateSectionKeyParams) => SectionKey
+}
+
+interface SectionToggleProviderProps {
+  children: ReactNode
+}
+
+export interface ToggleSectionDescriptor {
+  type: SectionEnum
+  index?: string | number
+  setTo?: boolean
+  id?: string
+}
+
+export interface ToggleOptions {
+  resetOthers?: boolean
+  filterKeys?: SectionEnum[]
+}
+
+interface GenerateSectionKeyParams {
+  apiId: string
+  type: SectionEnum
+  index?: string | number
+  id?: string | number
+}
+
+const SectionToggleContext = createContext<SectionToggleContextType | null>(null)
+
+export const useSectionToggle = () => {
+  const context = useContext(SectionToggleContext)
+  if (!context) {
+    throw new Error('useSectionToggle must be used within SectionToggleProvider')
+  }
+  return context
+}
+
+export const SectionToggleProvider = ({ children }: SectionToggleProviderProps) => {
+  const [expandedSections, setExpandedSections] = useState<ExpandedSections>({})
+
+  const generateSectionKey = ({ apiId, type, index, id }: GenerateSectionKeyParams): SectionKey => {
+    let key = `api_${apiId}_${type}`
+
+    if (index !== undefined) key += `_${index}`
+    if (id !== undefined) key += `_${id}`
+
+    return key as SectionKey
+  }
+
+  const toggleSection = useCallback(
+    (apiId: string, sections: ToggleSectionDescriptor[], options: ToggleOptions = {}) => {
+      const { resetOthers = false, filterKeys = [] } = options
+
+      const sectionIds = sections.map(({ type, index, id }) =>
+        generateSectionKey({ apiId, type, index, id })
+      )
+
+      const sectionToggles = Object.fromEntries(
+        sections.map(({ type, index, setTo, id }) => {
+          const sectionId = generateSectionKey({ apiId, type, index, id })
+          const currentValue = expandedSections[sectionId]
+
+          return [sectionId, setTo !== undefined ? setTo : !currentValue]
+        })
+      )
+
+      if (resetOthers && filterKeys.length > 0) {
+        const filtered = Object.fromEntries(
+          Object.entries(expandedSections).filter(([key]) => {
+            const shouldKeep = key.includes(apiId) && !filterKeys.some((k) => key.includes(k))
+            return shouldKeep || sectionIds.includes(key as SectionKey)
+          })
+        )
+        const newState = { ...filtered, ...sectionToggles }
+        setExpandedSections(newState)
+      } else {
+        setExpandedSections((prev) => {
+          const next = { ...prev, ...sectionToggles }
+
+          return next
+        })
+      }
+    },
+    [expandedSections]
+  )
+
+  const contextValue = useMemo(
+    () => ({
+      expandedSections,
+      toggleSection,
+      generateSectionKey,
+    }),
+    [expandedSections, toggleSection]
+  )
+
+  return (
+    <SectionToggleContext.Provider value={contextValue}>{children}</SectionToggleContext.Provider>
+  )
+}

package/src/global.d.ts

@@ -0,0 +1,13 @@
+declare module '*.module.css' {
+  const classes: { [key: string]: string }
+  export default classes
+}
+declare module '*.module.scss' {
+  const classes: { [key: string]: string }
+  export default classes
+}
+
+declare module '*.svg' {
+  const src: string
+  export default src
+}

package/src/helpers/docs.helper.ts

@@ -0,0 +1,42 @@
+import { ApiSpecModel } from '@entities/index'
+import { HTTPMethod, OpenAPIFile } from '@entities/openApi'
+import { nanoid } from 'nanoid'
+import { OverviewData, TagData } from 'src/layout/docsLayout'
+
+export const transformOpenApiToDocs = (api: ApiSpecModel): OverviewData => {
+  const parsedOpenApi: OpenAPIFile =
+    typeof api.metaData.openApiJson === 'string'
+      ? JSON.parse(api.metaData.openApiJson)
+      : api.metaData.openApiJson
+
+  const groupedPathsByTags: Record<string, TagData[]> = { default: [] }
+  const validTags = new Set(parsedOpenApi?.tags?.map(({ name }) => name) || [])
+
+  for (const [path, methods] of Object.entries(parsedOpenApi.paths)) {
+    for (const [method, methodData] of Object.entries(methods)) {
+      const entry = { ...methodData, method: method as HTTPMethod, path }
+      const resourceTags = methodData.tags ?? []
+
+      const matchedTags = resourceTags.filter((tag) => validTags.has(tag))
+
+      if (matchedTags.length > 0) {
+        matchedTags.forEach((tag) => {
+          if (!groupedPathsByTags[tag]) groupedPathsByTags[tag] = []
+          groupedPathsByTags[tag].push({ ...entry, id: nanoid(8) } as TagData)
+        })
+      } else {
+        groupedPathsByTags.default.push({ ...entry, id: nanoid(8) } as TagData)
+      }
+    }
+  }
+
+  return {
+    ...parsedOpenApi.info,
+    apiSpecId: api.apiSpecId,
+    contextPath: api.contextPath,
+    associatedProduct: api.associatedProduct,
+    apiVersions: api.apiVersions,
+    tags: groupedPathsByTags,
+    servers: parsedOpenApi.servers,
+  }
+}