@backstage/plugin-techdocs 1.0.1 → 1.1.1-next.0

package/dist/index.d.ts

@@ -1,33 +1,30 @@
 /// <reference types="react" />
-import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
+import { TechDocsMetadata, TechDocsEntityMetadata } from '@backstage/plugin-techdocs-react';
+import { CompoundEntityRef, Entity } from '@backstage/catalog-model';
 import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
 import { DiscoveryApi, FetchApi, IdentityApi } from '@backstage/core-plugin-api';
 import { Config } from '@backstage/config';
-import React, { PropsWithChildren } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode, PropsWithChildren } from 'react';
+import { ToolbarProps } from '@material-ui/core';
 import { TableColumn, TableProps } from '@backstage/core-components';
 import { UserListFilterKind } from '@backstage/plugin-catalog-react';
 import { CSSProperties } from '@material-ui/styles';
 
 /**
- * Metadata for TechDocs page
- *
- * @public
- */
-declare type TechDocsMetadata = {
-    site_name: string;
-    site_description: string;
-};
-/**
- * Metadata for TechDocs Entity
+ * Helper function that gives the children of {@link TechDocsReaderPage} access to techdocs and entity metadata
  *
  * @public
  */
-declare type TechDocsEntityMetadata = Entity & {
-    locationMetadata?: {
-        type: string;
-        target: string;
-    };
-};
+declare type TechDocsReaderPageRenderFunction = ({ techdocsMetadataValue, entityMetadataValue, entityRef, }: {
+    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;
 
 /**
  * Utility API reference for the {@link TechDocsStorageApi}.
@@ -39,6 +36,7 @@ declare const techdocsStorageApiRef: _backstage_core_plugin_api.ApiRef<TechDocsS
  * Utility API reference for the {@link TechDocsApi}.
  *
  * @public
+ * @deprecated Import from `@backstage/plugin-techdocs-react` instead
  */
 declare const techdocsApiRef: _backstage_core_plugin_api.ApiRef<TechDocsApi>;
 /**
@@ -64,6 +62,7 @@ interface TechDocsStorageApi {
  * API to talk to techdocs-backend.
  *
  * @public
+ * @deprecated Import from `@backstage/plugin-techdocs-react` instead
  */
 interface TechDocsApi {
     getApiOrigin(): Promise<string>;
@@ -147,58 +146,138 @@ declare class TechDocsStorageClient implements TechDocsStorageApi {
 }
 
 /**
- * Props for {@link Reader}
- *
+ * Props for {@link TechDocsReaderLayout}
  * @public
  */
-declare type ReaderProps = {
-    entityRef: CompoundEntityRef;
+declare type TechDocsReaderLayoutProps = {
+    /**
+     * Show or hide the header, defaults to true.
+     */
+    withHeader?: boolean;
+    /**
+     * Show or hide the content search bar, defaults to true.
+     */
     withSearch?: boolean;
-    onReady?: () => void;
 };
 /**
- * Component responsible for rendering TechDocs documentation
- *
+ * Default TechDocs reader page structure composed with a header and content
  * @public
  */
-declare const Reader: (props: ReaderProps) => JSX.Element;
-
+declare const TechDocsReaderLayout: ({ withSearch, withHeader, }: TechDocsReaderLayoutProps) => JSX.Element;
 /**
- * Helper function that gives the children of {@link TechDocsReaderPage} access to techdocs and entity metadata
- *
- * @public
- */
-declare type TechDocsReaderPageRenderFunction = ({ techdocsMetadataValue, entityMetadataValue, entityRef, }: {
-    techdocsMetadataValue?: TechDocsMetadata | undefined;
-    entityMetadataValue?: TechDocsEntityMetadata | undefined;
-    entityRef: CompoundEntityRef;
-    onReady: () => void;
-}) => JSX.Element;
-/**
- * Props for {@link TechDocsReaderPage}
- *
  * @public
  */
 declare type TechDocsReaderPageProps = {
-    children?: TechDocsReaderPageRenderFunction | React.ReactNode;
+    entityRef?: CompoundEntityRef;
+    children?: TechDocsReaderPageRenderFunction | ReactNode;
 };
 
 /**
  * Props for {@link TechDocsReaderPageHeader}
  *
  * @public
+ * @deprecated No need to pass down properties anymore. The component consumes data from `TechDocsReaderPageContext` instead. Use the {@link @backstage/plugin-techdocs-react#useTechDocsReaderPage} hook for custom header.
  */
 declare type TechDocsReaderPageHeaderProps = PropsWithChildren<{
-    entityRef: CompoundEntityRef;
+    entityRef?: CompoundEntityRef;
     entityMetadata?: TechDocsEntityMetadata;
     techDocsMetadata?: TechDocsMetadata;
 }>;
 /**
- * Component responsible for rendering a Header with metadata on TechDocs reader page.
+ * Renders the reader page header.
+ * This component does not accept props, please use
+ * the Tech Docs add-ons to customize it
+ * @public
+ */
+declare const TechDocsReaderPageHeader: (props: TechDocsReaderPageHeaderProps) => JSX.Element | null;
+
+/**
+ * Props for {@link TechDocsReaderPageContent}
+ * @public
+ */
+declare type TechDocsReaderPageContentProps = {
+    /**
+     * @deprecated No need to pass down entityRef as property anymore. Consumes the entityName from `TechDocsReaderPageContext`. Use the {@link @backstage/plugin-techdocs-react#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
+ */
+declare const TechDocsReaderPageContent: (props: TechDocsReaderPageContentProps) => JSX.Element;
+/**
+ * Component responsible for rendering TechDocs documentation
+ * @public
+ * @deprecated use `TechDocsReaderPageContent` component instead.
+ */
+declare const Reader: (props: TechDocsReaderPageContentProps) => JSX.Element;
+
+/**
+ * @public
+ * A state representation that is used to configure the UI of <Reader />
+ */
+declare type ContentStateTypes = 
+/** There is nothing to display but a loading indicator */
+'CHECKING'
+/** There is no content yet -> present a full screen loading page */
+ | 'INITIAL_BUILD'
+/** There is content, but the backend is about to update it */
+ | 'CONTENT_STALE_REFRESHING'
+/** There is content, but after a reload, the content will be different */
+ | 'CONTENT_STALE_READY'
+/** There is content, the backend tried to update it, but failed */
+ | 'CONTENT_STALE_ERROR'
+/** There is nothing to see but a "not found" page. Is also shown on page load errors */
+ | 'CONTENT_NOT_FOUND'
+/** There is only the latest and greatest content */
+ | 'CONTENT_FRESH';
+/**
+ * @public shared reader state
+ */
+declare type ReaderState = {
+    state: ContentStateTypes;
+    path: string;
+    contentReload: () => void;
+    content?: string;
+    contentErrorMessage?: string;
+    syncErrorMessage?: string;
+    buildLog: string[];
+};
+
+/**
+ * @public Render function for {@link TechDocsReaderProvider}
+ */
+declare type TechDocsReaderProviderRenderFunction = (value: ReaderState) => JSX.Element;
+/**
+ * @public Props for {@link TechDocsReaderProvider}
+ */
+declare type TechDocsReaderProviderProps = {
+    children: TechDocsReaderProviderRenderFunction | ReactNode;
+};
+/**
+ * Provides shared building process state to the reader page components.
  *
  * @public
  */
-declare const TechDocsReaderPageHeader: (props: TechDocsReaderPageHeaderProps) => JSX.Element;
+declare const TechDocsReaderProvider: ({ children, }: TechDocsReaderProviderProps) => JSX.Element;
+
+/**
+ * Renders the reader page subheader.
+ * Please use the Tech Docs add-ons to customize it
+ * @public
+ */
+declare const TechDocsReaderPageSubheader: ({ toolbarProps, }: {
+    toolbarProps?: ToolbarProps<"div", {}> | undefined;
+}) => JSX.Element | null;
 
 /**
  * Props for {@link TechDocsSearchResultListItem}.
@@ -415,7 +494,7 @@ declare type TechDocsCustomHomeProps = {
  * @public
  */
 declare type TechDocsPageWrapperProps = {
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
 };
 /**
  * Component wrapping a techdocs page with Page and Header components
@@ -456,7 +535,9 @@ declare const TechdocsPage: () => JSX.Element;
  *
  * @public
  */
-declare const EntityTechdocsContent: () => JSX.Element;
+declare const EntityTechdocsContent: (props: {
+    children?: React.ReactNode;
+}) => JSX.Element;
 /**
  * Component which takes a custom tabs config object and renders a documentation landing page.
  *
@@ -493,6 +574,25 @@ declare const Router: () => JSX.Element;
  *
  * @public
  */
-declare const EmbeddedDocsRouter: () => JSX.Element;
+declare const EmbeddedDocsRouter: (props: PropsWithChildren<{}>) => JSX.Element;
+
+/**
+ * The Backstage plugin that renders technical documentation for your components
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * @deprecated Import from `@backstage/plugin-techdocs-react` instead
+ *
+ * @public
+ */
+declare type DeprecatedTechDocsMetadata = TechDocsMetadata;
+/**
+ * @deprecated Import from `@backstage/plugin-techdocs-react` instead
+ *
+ * @public
+ */
+declare type DeprecatedTechDocsEntityMetadata = TechDocsEntityMetadata;
 
-export { DefaultTechDocsHome, DefaultTechDocsHomeProps, DocsCardGrid, DocsCardGridProps, DocsTable, DocsTableProps, DocsTableRow, EmbeddedDocsRouter, EntityListDocsGrid, EntityListDocsTable, EntityListDocsTableProps, EntityTechdocsContent, PanelConfig, PanelType, Reader, ReaderProps, Router, SyncResult, TabConfig, TabsConfig, TechDocsApi, TechDocsClient, TechDocsCustomHome, TechDocsCustomHomeProps, TechDocsEntityMetadata, TechDocsIndexPage, TechDocsMetadata, TechDocsPageWrapper, TechDocsPageWrapperProps, TechDocsPicker, TechDocsReaderPage, TechDocsReaderPageHeader, TechDocsReaderPageHeaderProps, TechDocsReaderPageProps, TechDocsReaderPageRenderFunction, TechDocsSearch, TechDocsSearchProps, TechDocsSearchResultListItem, TechDocsSearchResultListItemProps, TechDocsStorageApi, TechDocsStorageClient, TechdocsPage, isTechDocsAvailable, techdocsPlugin as plugin, techdocsApiRef, techdocsPlugin, techdocsStorageApiRef };
+export { ContentStateTypes, DefaultTechDocsHome, DefaultTechDocsHomeProps, DocsCardGrid, DocsCardGridProps, DocsTable, DocsTableProps, DocsTableRow, EmbeddedDocsRouter, EntityListDocsGrid, EntityListDocsTable, EntityListDocsTableProps, EntityTechdocsContent, PanelConfig, PanelType, Reader, ReaderState, Router, SyncResult, TabConfig, TabsConfig, TechDocsApi, TechDocsClient, TechDocsCustomHome, TechDocsCustomHomeProps, DeprecatedTechDocsEntityMetadata as TechDocsEntityMetadata, TechDocsIndexPage, DeprecatedTechDocsMetadata as TechDocsMetadata, TechDocsPageWrapper, TechDocsPageWrapperProps, TechDocsPicker, TechDocsReaderLayout, TechDocsReaderLayoutProps, TechDocsReaderPage, TechDocsReaderPageContent, TechDocsReaderPageContentProps, TechDocsReaderPageHeader, TechDocsReaderPageHeaderProps, TechDocsReaderPageProps, TechDocsReaderPageRenderFunction, TechDocsReaderPageSubheader, TechDocsReaderProvider, TechDocsReaderProviderProps, TechDocsReaderProviderRenderFunction, TechDocsSearch, TechDocsSearchProps, TechDocsSearchResultListItem, TechDocsSearchResultListItemProps, TechDocsStorageApi, TechDocsStorageClient, TechdocsPage, isTechDocsAvailable, techdocsPlugin as plugin, techdocsApiRef, techdocsPlugin, techdocsStorageApiRef };