feat: Add API reference docs for webapp-tenants (#548)

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

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.

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',
       {

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',
       ],
     },
   ],

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;

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();
 

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(() => {

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 <TenantWrapper>{children}</TenantWrapper>;
 }
 
+/** @ignore */
 export function getWrapper(
   WrapperComponent: ComponentClass<WrapperProps> | FC<WrapperProps>,
   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<Q, Container, BaseElement> & 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<Q, Container, BaseElement> = {}
+): RenderResult<Q, Container, BaseElement> & { 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<Result, Props>(hook: (initialProps: Props) => Result, options: CustomRenderOptions = {}) {
   const { wrapper, waitForApolloMocks } = getWrapper(TenantsTestProviders, options);
 
@@ -79,15 +108,19 @@ export const createMockRouterProps = (pathName: string, params?: Record<string,
   };
 };
 
+/** @ignore */
 export const PLACEHOLDER_TEST_ID = 'content';
+/** @ignore */
 export const PLACEHOLDER_CONTENT = <span data-testid="content">content</span>;
 
+/** @ignore */
 const CurrentTenantRouteElement = () => (
   <CurrentTenantProvider>
     <Outlet />
   </CurrentTenantProvider>
 );
 
+/** @ignore */
 export const CurrentTenantRouteWrapper = ({ children }: PropsWithChildren) => {
   return (
     <Routes>