From b43f3f06a3fe0af06e697e917fcab0329d66a4e2 Mon Sep 17 00:00:00 2001 From: mkleszcz Date: Mon, 13 May 2024 16:16:48 +0200 Subject: [PATCH] feat: Add API reference docs for webapp-tenants (#548) --- packages/internal/docs/.gitignore | 1 + .../api-reference/webapp-tenants/commands.mdx | 30 ++++++++++++++ packages/internal/docs/docusaurus.config.js | 15 +++++++ packages/internal/docs/sidebars.js | 13 +++++- .../useCurrentTenantRole.hook.ts | 9 ++++ .../useTenantRoles/useTenantRoles.hook.ts | 10 +++++ .../src/hooks/useTenants/useTenants.hook.ts | 7 ++++ .../src/tests/utils/rendering.tsx | 41 +++++++++++++++++-- 8 files changed, 121 insertions(+), 5 deletions(-) create mode 100644 packages/internal/docs/docs/api-reference/webapp-tenants/commands.mdx diff --git a/packages/internal/docs/.gitignore b/packages/internal/docs/.gitignore index 488b8e8b2..bd80eac74 100644 --- a/packages/internal/docs/.gitignore +++ b/packages/internal/docs/.gitignore @@ -26,4 +26,5 @@ yarn-error.log* docs/api-reference/webapp/generated docs/api-reference/webapp-core/generated docs/api-reference/webapp-api-client/generated +docs/api-reference/webapp-tenants/generated docs/api-reference/backend/generated diff --git a/packages/internal/docs/docs/api-reference/webapp-tenants/commands.mdx b/packages/internal/docs/docs/api-reference/webapp-tenants/commands.mdx new file mode 100644 index 000000000..510fd11f9 --- /dev/null +++ b/packages/internal/docs/docs/api-reference/webapp-tenants/commands.mdx @@ -0,0 +1,30 @@ +--- +title: CLI commands +description: Commands within `webapp-tenants` package context +--- + +This page contains a list of CLI commands that you can use within the `webapp-tenants` package context. + +--- + +### `pnpm run lint` + +Runs `eslint` and `stylelint` for the `webapp` package. + +--- + +### `pnpm run type-check` + +Runs `tsc` compilation with disabled files emitting. + +--- + +### `pnpm run test` + +Runs `jest` for the `webapp` package. + +--- + +### `pnpm run test:watch` + +Runs `jest` with `--watch` flag. Useful for development purpose. diff --git a/packages/internal/docs/docusaurus.config.js b/packages/internal/docs/docusaurus.config.js index 47e50f5d0..93d2baab2 100644 --- a/packages/internal/docs/docusaurus.config.js +++ b/packages/internal/docs/docusaurus.config.js @@ -124,6 +124,21 @@ module.exports = { watch: process.env.TYPEDOC_WATCH, }, ], + [ + 'docusaurus-plugin-typedoc', + { + id: 'typedoc-webapp-tenants', + entryPoints: [ + '../../webapp-libs/webapp-tenants/src/hooks/index.ts', + '../../webapp-libs/webapp-tenants/src/providers/index.ts', + '../../webapp-libs/webapp-tenants/src/tests/utils/rendering.tsx', + ], + tsconfig: '../../webapp-libs/webapp-tenants/tsconfig.lib.json', + out: 'api-reference/webapp-tenants/generated', + readme: 'none', + watch: process.env.TYPEDOC_WATCH, + }, + ], [ 'docusaurus-plugin-typedoc', { diff --git a/packages/internal/docs/sidebars.js b/packages/internal/docs/sidebars.js index 7c8f09abe..3d6bb76c4 100644 --- a/packages/internal/docs/sidebars.js +++ b/packages/internal/docs/sidebars.js @@ -118,6 +118,17 @@ module.exports = { collapsed: false, items: ['api-reference/webapp-emails/commands'], }, + { + type: 'category', + label: 'webapp-tenants', + collapsed: false, + items: [ + { + type: 'autogenerated', + dirName: 'api-reference/webapp-tenants/generated', + }, + ], + }, { type: 'category', label: 'tools', @@ -208,7 +219,7 @@ module.exports = { 'aws/architecture/cicd-architecture', ], }, - 'aws/troubleshooting' + 'aws/troubleshooting', ], }, ], diff --git a/packages/webapp-libs/webapp-tenants/src/hooks/useCurrentTenantRole/useCurrentTenantRole.hook.ts b/packages/webapp-libs/webapp-tenants/src/hooks/useCurrentTenantRole/useCurrentTenantRole.hook.ts index 2d758cf0e..ce54797ec 100644 --- a/packages/webapp-libs/webapp-tenants/src/hooks/useCurrentTenantRole/useCurrentTenantRole.hook.ts +++ b/packages/webapp-libs/webapp-tenants/src/hooks/useCurrentTenantRole/useCurrentTenantRole.hook.ts @@ -1,5 +1,14 @@ import { useCurrentTenant } from '../../providers'; +/** + * Hook that retrieves the user's role of the current tenant. + * + * This hook uses the `useCurrentTenant` hook to get the current tenant's data, and then extracts the role from the + * tenant's membership data. + * + * @returns {string | null} The role of the current tenant if available, or `null` otherwise. + * + */ export const useCurrentTenantRole = () => { const currentTenant = useCurrentTenant(); const membership = currentTenant?.data?.membership; diff --git a/packages/webapp-libs/webapp-tenants/src/hooks/useTenantRoles/useTenantRoles.hook.ts b/packages/webapp-libs/webapp-tenants/src/hooks/useTenantRoles/useTenantRoles.hook.ts index c7cf93aad..e2a06e47d 100644 --- a/packages/webapp-libs/webapp-tenants/src/hooks/useTenantRoles/useTenantRoles.hook.ts +++ b/packages/webapp-libs/webapp-tenants/src/hooks/useTenantRoles/useTenantRoles.hook.ts @@ -1,6 +1,16 @@ import { TenantUserRole } from '@sb/webapp-api-client'; import { useIntl } from 'react-intl'; +/** + * Hook that provides translations for tenant roles. + * + * The hook returns an object with two properties: + * - `roleTranslations`: an object mapping each role to its translated string. + * - `getRoleTranslation`: a function that takes a role and returns its translated string. + * + * @returns {Object} An object containing role translations and a function to get role translation. + * + */ export const useTenantRoles = () => { const intl = useIntl(); diff --git a/packages/webapp-libs/webapp-tenants/src/hooks/useTenants/useTenants.hook.ts b/packages/webapp-libs/webapp-tenants/src/hooks/useTenants/useTenants.hook.ts index 95a8853a4..86b5dad09 100644 --- a/packages/webapp-libs/webapp-tenants/src/hooks/useTenants/useTenants.hook.ts +++ b/packages/webapp-libs/webapp-tenants/src/hooks/useTenants/useTenants.hook.ts @@ -2,6 +2,13 @@ import { getFragmentData } from '@sb/webapp-api-client/graphql'; import { commonQueryTenantItemFragment, useCommonQuery } from '@sb/webapp-api-client/providers'; import { useMemo } from 'react'; +/** + * Hook that retrieves the current user's tenants. + * + * This hook uses the `useCommonQuery` hook to get the current user's data, and then extracts the tenants from it. + * + * @returns {Array} An array of the current user's tenants. + */ export const useTenants = () => { const { data } = useCommonQuery(); return useMemo(() => { diff --git a/packages/webapp-libs/webapp-tenants/src/tests/utils/rendering.tsx b/packages/webapp-libs/webapp-tenants/src/tests/utils/rendering.tsx index 237721520..fabb648bc 100644 --- a/packages/webapp-libs/webapp-tenants/src/tests/utils/rendering.tsx +++ b/packages/webapp-libs/webapp-tenants/src/tests/utils/rendering.tsx @@ -1,6 +1,7 @@ import * as apiUtils from '@sb/webapp-api-client/tests/utils/rendering'; import * as corePath from '@sb/webapp-core/utils/path'; -import { RenderOptions, render, renderHook } from '@testing-library/react'; +import { Queries, queries } from '@testing-library/dom'; +import { RenderOptions, RenderResult, render, renderHook } from '@testing-library/react'; import { ComponentClass, ComponentType, FC, PropsWithChildren, ReactElement } from 'react'; import { MemoryRouterProps, generatePath } from 'react-router'; import { Outlet, Route, Routes } from 'react-router-dom'; @@ -12,7 +13,7 @@ export type WrapperProps = apiUtils.WrapperProps & { }; /** - * Component that wraps `children` with `CurrentTenant` + * Component that wraps `children` with [`CurrentTenantProvider`](./providers#currenttenantprovider) * @param children * @param TenantWrapper * @constructor @@ -21,6 +22,7 @@ export function TenantsTestProviders({ children, TenantWrapper = CurrentTenantPr return {children}; } +/** @ignore */ export function getWrapper( WrapperComponent: ComponentClass | FC, wrapperProps: WrapperProps @@ -40,9 +42,28 @@ export function getWrapper( }; } -export type CustomRenderOptions = RenderOptions & WrapperProps; +export type CustomRenderOptions< + Q extends Queries = typeof queries, + Container extends Element | DocumentFragment = HTMLElement, + BaseElement extends Element | DocumentFragment = Container, +> = RenderOptions & WrapperProps; -function customRender(ui: ReactElement, options: CustomRenderOptions = {}) { +/** + * Method that extends [`render`](https://testing-library.com/docs/react-testing-library/api#render) method from + * `@testing-library/react` package. It composes a wrapper using [`TenantsTestProviders`](#tenantstestproviders) + * component. + * + * @param ui + * @param options + */ +function customRender< + Q extends Queries = typeof queries, + Container extends Element | DocumentFragment = HTMLElement, + BaseElement extends Element | DocumentFragment = Container, +>( + ui: ReactElement, + options: CustomRenderOptions = {} +): RenderResult & { waitForApolloMocks: apiUtils.WaitForApolloMocks } { const { wrapper, waitForApolloMocks } = getWrapper(TenantsTestProviders, options); return { @@ -54,6 +75,14 @@ function customRender(ui: ReactElement, options: CustomRenderOptions = {}) { }; } +/** + * Method that extends [`renderHook`](https://testing-library.com/docs/react-testing-library/api#renderhook) method from + * `@testing-library/react` package. It composes a wrapper using [`TenantsTestProviders`](#tenantstestproviders) + * component. + * + * @param hook + * @param options + */ function customRenderHook(hook: (initialProps: Props) => Result, options: CustomRenderOptions = {}) { const { wrapper, waitForApolloMocks } = getWrapper(TenantsTestProviders, options); @@ -79,15 +108,19 @@ export const createMockRouterProps = (pathName: string, params?: Recordcontent; +/** @ignore */ const CurrentTenantRouteElement = () => ( ); +/** @ignore */ export const CurrentTenantRouteWrapper = ({ children }: PropsWithChildren) => { return (