fix(techdocs): update api reports

Co-authored-by: Emma Indal <emma.indahl@gmail.com>
Signed-off-by: Camila Belo <camilaibs@gmail.com>

plugins/techdocs/src/reader/components/TechDocsReaderPage/TechDocsReaderPage.tsx

@@ -37,11 +37,25 @@ type Extension = ReactChild & {
   };
 };
 
+/**
+ * Props for {@link TechDocsReaderLayout}
+ * @public
+ */
 export type TechDocsReaderLayoutProps = {
+  /**
+   * Show or hide the header, defaults to true.
+   */
   withHeader?: boolean;
+  /**
+   * Show or hide the content search bar, defaults to true.
+   */
   withSearch?: boolean;
 };
 
+/**
+ * Default TechDocs reader page structure composed with a header and content
+ * @public
+ */
 export const TechDocsReaderLayout = ({
   withSearch,
   withHeader = true,
@@ -96,13 +110,14 @@ export const TechDocsReaderPage = ({
 
   return (
     <TechDocsReaderPageProvider entityName={entityName}>
-      {({ metadata, entityMetadata }) => (
+      {({ metadata, entityMetadata, onReady }) => (
         <Page themeId="documentation">
           {children instanceof Function
             ? children({
                 entityRef: entityName,
                 techdocsMetadataValue: metadata.value,
                 entityMetadataValue: entityMetadata.value,
+                onReady,
               })
             : children}
         </Page>

plugins/techdocs/src/reader/components/TechDocsReaderPage/context.tsx

@@ -47,6 +47,10 @@ const areEntityNamesEqual = (
   return true;
 };
 
+/**
+ * @public type for the value of the TechDocsReaderPageContext
+ */
+
 export type TechDocsReaderPageValue = {
   metadata: AsyncState<TechDocsMetadata>;
   entityName: CompoundEntityRef;
@@ -57,6 +61,10 @@ export type TechDocsReaderPageValue = {
   setTitle: Dispatch<SetStateAction<string>>;
   subtitle: string;
   setSubtitle: Dispatch<SetStateAction<string>>;
+  /**
+   * @deprecated property can be passed down directly to the `TechDocsReaderPageContent` instead.
+   */
+  onReady?: () => void;
 };
 
 export const defaultTechDocsReaderPageValue: TechDocsReaderPageValue = {
@@ -73,20 +81,37 @@ export const defaultTechDocsReaderPageValue: TechDocsReaderPageValue = {
 export const TechDocsReaderPageContext = createContext<TechDocsReaderPageValue>(
   defaultTechDocsReaderPageValue,
 );
-
+/**
+ * Hook used to get access to shared state between reader page components.
+ * @public
+ */
 export const useTechDocsReaderPage = () => {
   return useContext(TechDocsReaderPageContext);
 };
 
-type TechDocsReaderPageProviderRenderFunction = (
+/**
+ * render function for {@link TechDocsReaderPageProvider}
+ *
+ * @public
+ */
+export type TechDocsReaderPageProviderRenderFunction = (
   value: TechDocsReaderPageValue,
 ) => JSX.Element;
 
-type TechDocsReaderPageProviderProps = {
+/**
+ * Props for {@link TechDocsReaderPageProvider}
+ *
+ * @public
+ */
+export type TechDocsReaderPageProviderProps = {
   entityName: CompoundEntityRef;
   children: TechDocsReaderPageProviderRenderFunction | ReactNode;
 };
 
+/**
+ * A context to store the reader page state
+ * @public
+ */
 export const TechDocsReaderPageProvider = memo(
   ({ entityName, children }: TechDocsReaderPageProviderProps) => {
     const techdocsApi = useApi(techdocsApiRef);

plugins/techdocs/src/reader/components/TechDocsReaderPageContent/TechDocsReaderPageContent.tsx

@@ -24,6 +24,7 @@ import {
   useTechDocsAddons,
   TechDocsAddonLocations as locations,
 } from '@backstage/techdocs-addons';
+import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Content, Progress } from '@backstage/core-components';
 
 import { TechDocsSearch } from '../../../search';
@@ -43,13 +44,32 @@ const useStyles = makeStyles({
   },
 });
 
+/**
+ * Props for {@link TechDocsReaderPageContent}
+ * @public
+ */
 export type TechDocsReaderPageContentProps = {
+  /**
+   * @deprecated No need to pass down entityRef as property anymore. Consumes the entityName from `TechDocsReaderPageContext`. Use the {@link useTechDocsReaderPage} hook for custom reader page content.
+   */
+  entityRef?: CompoundEntityRef;
+  /**
+   * Show or hide the search bar, defaults to true.
+   */
   withSearch?: boolean;
+  /**
+   * Callback called when the content is rendered.
+   */
   onReady?: () => void;
 };
 
+/**
+ * Renders the reader page content
+ * @public
+ */
 export const TechDocsReaderPageContent = withTechDocsReaderProvider(
-  ({ withSearch = true, onReady }: TechDocsReaderPageContentProps) => {
+  (props: TechDocsReaderPageContentProps) => {
+    const { withSearch = true, onReady } = props;
     const classes = useStyles();
     const addons = useTechDocsAddons();
     const { entityName, shadowRoot, setShadowRoot } = useTechDocsReaderPage();
@@ -141,3 +161,18 @@ export const TechDocsReaderPageContent = withTechDocsReaderProvider(
     );
   },
 );
+
+/**
+ * Props for {@link Reader}
+ *
+ * @public
+ * @deprecated use `TechDocsReaderPageContentProps` instead.
+ */
+export type ReaderProps = TechDocsReaderPageContentProps;
+
+/**
+ * Component responsible for rendering TechDocs documentation
+ * @public
+ * @deprecated use `TechDocsReaderPageContent` component instead.
+ */
+export const Reader = TechDocsReaderPageContent;

plugins/techdocs/src/reader/components/TechDocsReaderPageContent/context.tsx

@@ -22,27 +22,10 @@ import React, {
 } from 'react';
 import { useParams } from 'react-router-dom';
 
-import { CompoundEntityRef } from '@backstage/catalog-model';
-
-import { useReaderState } from '../useReaderState';
+import { useReaderState, ReaderState } from '../useReaderState';
 import { useTechDocsReaderPage } from '../TechDocsReaderPage';
 
-/**
- * Props for {@link Reader}
- *
- * @public
- */
-export type ReaderProps = {
-  entityRef: CompoundEntityRef;
-  withSearch?: boolean;
-  onReady?: () => void;
-};
-
-type TechDocsReaderValue = ReturnType<typeof useReaderState>;
-
-const TechDocsReaderContext = createContext<TechDocsReaderValue>(
-  {} as TechDocsReaderValue,
-);
+const TechDocsReaderContext = createContext<ReaderState>({} as ReaderState);
 
 /**
  * Note: this hook is currently being exported so that we can rapidly
@@ -56,14 +39,25 @@ const TechDocsReaderContext = createContext<TechDocsReaderValue>(
 
 export const useTechDocsReader = () => useContext(TechDocsReaderContext);
 
-type TechDocsReaderProviderRenderFunction = (
-  value: TechDocsReaderValue,
+/**
+ * @public Render function for {@link TechDocsReaderProvider}
+ */
+export type TechDocsReaderProviderRenderFunction = (
+  value: ReaderState,
 ) => JSX.Element;
 
-type TechDocsReaderProviderProps = {
+/**
+ * @public Props for {@link TechDocsReaderProvider}
+ */
+export type TechDocsReaderProviderProps = {
   children: TechDocsReaderProviderRenderFunction | ReactNode;
 };
 
+/**
+ * Provides shared building process state to the reader page components.
+ *
+ * @public
+ */
 export const TechDocsReaderProvider = ({
   children,
 }: TechDocsReaderProviderProps) => {

plugins/techdocs/src/reader/components/TechDocsReaderPageContent/index.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
-export { TechDocsReaderPageContent } from './TechDocsReaderPageContent';
+export { TechDocsReaderPageContent, Reader } from './TechDocsReaderPageContent';
+export type { TechDocsReaderPageContentProps } from './TechDocsReaderPageContent';
 export * from './context';
 export * from './dom';

plugins/techdocs/src/reader/components/TechDocsReaderPageHeader/TechDocsReaderPageHeader.tsx

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import React, { useEffect } from 'react';
+import React, { PropsWithChildren, useEffect } from 'react';
 import Helmet from 'react-helmet';
 
 import { Skeleton } from '@material-ui/lab';
@@ -29,17 +29,39 @@ import {
   EntityRefLinks,
   getEntityRelations,
 } from '@backstage/plugin-catalog-react';
-import { RELATION_OWNED_BY } from '@backstage/catalog-model';
+import { RELATION_OWNED_BY, CompoundEntityRef } from '@backstage/catalog-model';
 import { Header, HeaderLabel } from '@backstage/core-components';
 import { useRouteRef, configApiRef, useApi } from '@backstage/core-plugin-api';
 
 import { useTechDocsReaderPage } from '../TechDocsReaderPage';
 
 import { rootRouteRef } from '../../../routes';
+import { TechDocsEntityMetadata, TechDocsMetadata } from '../../../types';
 
 const skeleton = <Skeleton animation="wave" variant="text" height={40} />;
 
-export const TechDocsReaderPageHeader = () => {
+/**
+ * Props for {@link TechDocsReaderPageHeader}
+ *
+ * @public
+ * @deprecated No need to pass down properties anymore. The component consumes data from `TechDocsReaderPageContext` instead. Use the {@link useTechDocsReaderPage} hook for custom header.
+ */
+export type TechDocsReaderPageHeaderProps = PropsWithChildren<{
+  entityRef?: CompoundEntityRef;
+  entityMetadata?: TechDocsEntityMetadata;
+  techDocsMetadata?: TechDocsMetadata;
+}>;
+
+/**
+ * Renders the reader page header.
+ * This component does not accept props, please use
+ * the Tech Docs add-ons to customize it
+ * @public
+ */
+export const TechDocsReaderPageHeader = (
+  props: TechDocsReaderPageHeaderProps,
+) => {
+  const { children } = props;
   const addons = useTechDocsAddons();
   const configApi = useApi(configApiRef);
 
@@ -61,7 +83,7 @@ export const TechDocsReaderPageHeader = () => {
     });
     setSubtitle(prevSubtitle => {
       let { site_description } = metadata;
-      if (site_description === 'None') {
+      if (!site_description || site_description === 'None') {
         site_description = 'Home';
       }
       return prevSubtitle || site_description;
@@ -135,6 +157,7 @@ export const TechDocsReaderPageHeader = () => {
         <title>{tabTitle}</title>
       </Helmet>
       {labels}
+      {children}
       {addons.renderComponentsByLocation(locations.HEADER)}
     </Header>
   );

plugins/techdocs/src/reader/components/TechDocsReaderPageHeader/index.ts

@@ -15,3 +15,4 @@
  */
 
 export { TechDocsReaderPageHeader } from './TechDocsReaderPageHeader';
+export type { TechDocsReaderPageHeaderProps } from './TechDocsReaderPageHeader';

plugins/techdocs/src/reader/components/index.ts

@@ -17,6 +17,9 @@
 export type {
   TechDocsReaderPageProps,
   TechDocsReaderLayoutProps,
+  TechDocsReaderPageValue,
+  TechDocsReaderPageProviderProps,
+  TechDocsReaderPageProviderRenderFunction,
 } from './TechDocsReaderPage';
 export {
   useShadowRoot,
@@ -30,3 +33,4 @@ export {
 export * from './TechDocsReaderPageHeader';
 export * from './TechDocsReaderPageContent';
 export * from './TechDocsStateIndicator';
+export type { ReaderState, ContentStateTypes } from './useReaderState';

plugins/techdocs/src/reader/components/useReaderState.ts

@@ -21,9 +21,10 @@ import useAsyncRetry from 'react-use/lib/useAsyncRetry';
 import { techdocsStorageApiRef } from '../../api';
 
 /**
+ * @public
  * A state representation that is used to configure the UI of <Reader />
  */
-type ContentStateTypes =
+export type ContentStateTypes =
   /** There is nothing to display but a loading indicator */
   | 'CHECKING'
 
@@ -224,13 +225,10 @@ export function reducer(
 
   return newState;
 }
-
-export function useReaderState(
-  kind: string,
-  namespace: string,
-  name: string,
-  path: string,
-): {
+/**
+ * @public shared reader state
+ */
+export type ReaderState = {
   state: ContentStateTypes;
   path: string;
   contentReload: () => void;
@@ -238,7 +236,14 @@ export function useReaderState(
   contentErrorMessage?: string;
   syncErrorMessage?: string;
   buildLog: string[];
-} {
+};
+
+export function useReaderState(
+  kind: string,
+  namespace: string,
+  name: string,
+  path: string,
+): ReaderState {
   const [state, dispatch] = useReducer(reducer, {
     activeSyncState: 'CHECKING',
     path,

plugins/techdocs/src/types.ts

@@ -29,6 +29,10 @@ export type TechDocsReaderPageRenderFunction = ({
   techdocsMetadataValue?: TechDocsMetadata | undefined;
   entityMetadataValue?: TechDocsEntityMetadata | undefined;
   entityRef: CompoundEntityRef;
+  /**
+   * @deprecated You can continue pass this property, but directly to the `TechDocsReaderPageContent` component.
+   */
+  onReady?: () => void;
 }) => JSX.Element;
 
 /**