@backstage/plugin-techdocs 0.13.3 → 0.15.0

package/dist/index.d.ts

@@ -1,22 +1,32 @@
 /// <reference types="react" />
+import { Entity, CompoundEntityRef } 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 * as _backstage_catalog_model from '@backstage/catalog-model';
-import { Entity, LocationSpec, EntityName } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
-import * as _backstage_core_components from '@backstage/core-components';
+import React, { PropsWithChildren } from 'react';
 import { TableColumn, TableProps } from '@backstage/core-components';
 import { UserListFilterKind } from '@backstage/plugin-catalog-react';
 import { CSSProperties } from '@material-ui/styles';
-import React from 'react';
-import * as _material_table_core from '@material-table/core';
 
+/**
+ * Metadata for TechDocs page
+ *
+ * @public
+ */
 declare type TechDocsMetadata = {
     site_name: string;
     site_description: string;
 };
+/**
+ * Metadata for TechDocs Entity
+ *
+ * @public
+ */
 declare type TechDocsEntityMetadata = Entity & {
-    locationMetadata?: LocationSpec;
+    locationMetadata?: {
+        type: string;
+        target: string;
+    };
 };
 
 /**
@@ -49,9 +59,9 @@ interface TechDocsStorageApi {
     getApiOrigin(): Promise<string>;
     getStorageUrl(): Promise<string>;
     getBuilder(): Promise<string>;
-    getEntityDocs(entityId: EntityName, path: string): Promise<string>;
-    syncEntityDocs(entityId: EntityName, logHandler?: (line: string) => void): Promise<SyncResult>;
-    getBaseUrl(oldBaseUrl: string, entityId: EntityName, path: string): Promise<string>;
+    getEntityDocs(entityId: CompoundEntityRef, path: string): Promise<string>;
+    syncEntityDocs(entityId: CompoundEntityRef, logHandler?: (line: string) => void): Promise<SyncResult>;
+    getBaseUrl(oldBaseUrl: string, entityId: CompoundEntityRef, path: string): Promise<string>;
 }
 /**
  * API to talk to techdocs-backend.
@@ -63,8 +73,8 @@ interface TechDocsApi {
      * Set to techdocs.requestUrl as the URL for techdocs-backend API.
      */
     getApiOrigin(): Promise<string>;
-    getTechDocsMetadata(entityId: EntityName): Promise<TechDocsMetadata>;
-    getEntityMetadata(entityId: EntityName): Promise<TechDocsEntityMetadata>;
+    getTechDocsMetadata(entityId: CompoundEntityRef): Promise<TechDocsMetadata>;
+    getEntityMetadata(entityId: CompoundEntityRef): Promise<TechDocsEntityMetadata>;
 }
 
 /**
@@ -91,7 +101,7 @@ declare class TechDocsClient implements TechDocsApi {
      *
      * @param entityId - Object containing entity data like name, namespace, etc.
      */
-    getTechDocsMetadata(entityId: EntityName): Promise<TechDocsMetadata>;
+    getTechDocsMetadata(entityId: CompoundEntityRef): Promise<TechDocsMetadata>;
     /**
      * Retrieve metadata about an entity.
      *
@@ -100,7 +110,7 @@ declare class TechDocsClient implements TechDocsApi {
      *
      * @param entityId - Object containing entity data like name, namespace, etc.
      */
-    getEntityMetadata(entityId: EntityName): Promise<TechDocsEntityMetadata>;
+    getEntityMetadata(entityId: CompoundEntityRef): Promise<TechDocsEntityMetadata>;
 }
 /**
  * API which talks to TechDocs storage to fetch files to render.
@@ -129,7 +139,7 @@ declare class TechDocsStorageClient implements TechDocsStorageApi {
      * @returns HTML content of the docs page as string
      * @throws Throws error when the page is not found.
      */
-    getEntityDocs(entityId: EntityName, path: string): Promise<string>;
+    getEntityDocs(entityId: CompoundEntityRef, path: string): Promise<string>;
     /**
      * Check if docs are on the latest version and trigger rebuild if not
      *
@@ -138,83 +148,267 @@ declare class TechDocsStorageClient implements TechDocsStorageApi {
      * @returns Whether documents are currently synchronized to newest version
      * @throws Throws error on error from sync endpoint in Techdocs Backend
      */
-    syncEntityDocs(entityId: EntityName, logHandler?: (line: string) => void): Promise<SyncResult>;
-    getBaseUrl(oldBaseUrl: string, entityId: EntityName, path: string): Promise<string>;
+    syncEntityDocs(entityId: CompoundEntityRef, logHandler?: (line: string) => void): Promise<SyncResult>;
+    getBaseUrl(oldBaseUrl: string, entityId: CompoundEntityRef, path: string): Promise<string>;
 }
 
-declare const DocsResultListItem: ({ result, lineClamp, asListItem, asLink, title, }: {
-    result: any;
-    lineClamp?: number | undefined;
-    asListItem?: boolean | undefined;
-    asLink?: boolean | undefined;
-    title?: string | undefined;
+/**
+ * Props for {@link Reader}
+ *
+ * @public
+ */
+declare type ReaderProps = {
+    entityRef: CompoundEntityRef;
+    withSearch?: boolean;
+    onReady?: () => void;
+};
+/**
+ * Component responsible for rendering TechDocs documentation
+ *
+ * @public
+ */
+declare const Reader: (props: ReaderProps) => 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;
+};
+/**
+ * @public
+ * @deprecated use {@link TechDocsReaderPage} instead
+ */
+declare const TechDocsPage: (props: TechDocsReaderPageProps) => JSX.Element;
+/**
+ * @public
+ * @deprecated use {@link TechDocsReaderPageRenderFunction} instead
+ */
+declare type TechDocsPageRenderFunction = TechDocsReaderPageRenderFunction;
+
+/**
+ * Props for {@link TechDocsReaderPageHeader}
+ *
+ * @public
+ */
+declare type TechDocsReaderPageHeaderProps = PropsWithChildren<{
+    entityRef: CompoundEntityRef;
+    entityMetadata?: TechDocsEntityMetadata;
+    techDocsMetadata?: TechDocsMetadata;
+}>;
+/**
+ * Component responsible for rendering a Header with metadata on TechDocs reader page.
+ *
+ * @public
+ */
+declare const TechDocsReaderPageHeader: (props: TechDocsReaderPageHeaderProps) => JSX.Element;
+/**
+ * @public
+ * @deprecated use {@link TechDocsReaderPageHeader} instead
+ */
+declare const TechDocsPageHeader: (props: TechDocsReaderPageHeaderProps) => JSX.Element;
+/**
+ * @public
+ * @deprecated use {@link TechDocsReaderPageHeader} instead
+ */
+declare type TechDocsPageHeaderProps = TechDocsReaderPageHeaderProps;
+
+/**
+ * Props for {@link TechDocsSearchResultListItem}.
+ *
+ * @public
+ */
+declare type TechDocsSearchResultListItemProps = {
+    result: any;
+    lineClamp?: number;
+    asListItem?: boolean;
+    asLink?: boolean;
+    title?: string;
+};
+/**
+ * Component which renders documentation and related metadata.
+ *
+ * @public
+ */
+declare const TechDocsSearchResultListItem: (props: TechDocsSearchResultListItemProps) => JSX.Element;
+/**
+ * @public
+ * @deprecated use {@link TechDocsSearchResultListItem} instead
+ */
+declare const DocsResultListItem: (props: TechDocsSearchResultListItemProps) => JSX.Element;
+
+/**
+ * Props for {@link TechDocsSearch}
+ *
+ * @public
+ */
+declare type TechDocsSearchProps = {
+    entityId: CompoundEntityRef;
+    debounceTime?: number;
+};
+/**
+ * Component used to render search bar on TechDocs page, scoped to
+ *
+ * @public
+ */
+declare const TechDocsSearch: (props: TechDocsSearchProps) => JSX.Element;
 
+/**
+ * Component responsible to get entities from entity list context and pass down to DocsCardGrid
+ *
+ * @public
+ */
+declare const EntityListDocsGrid: () => JSX.Element;
+
+/**
+ * Props for {@link DocsCardGrid}
+ *
+ * @public
+ */
+declare type DocsCardGridProps = {
+    entities: Entity[] | undefined;
+};
+/**
+ * Component which accepts a list of entities and renders a item card for each entity
+ *
+ * @public
+ */
+declare const DocsCardGrid: (props: DocsCardGridProps) => JSX.Element | null;
+
+/**
+ * Generic representing the metadata structure for a docs table row.
+ *
+ * @public
+ */
 declare type DocsTableRow = {
     entity: Entity;
     resolved: {
         docsUrl: string;
         ownedByRelationsTitle: string;
-        ownedByRelations: EntityName[];
+        ownedByRelations: CompoundEntityRef[];
     };
 };
 
-declare const DefaultTechDocsHome: ({ initialFilter, columns, actions, }: {
-    initialFilter?: UserListFilterKind | undefined;
-    columns?: TableColumn<DocsTableRow>[] | undefined;
+/**
+ * Props for {@link EntityListDocsTable}.
+ *
+ * @public
+ */
+declare type EntityListDocsTableProps = {
+    columns?: TableColumn<DocsTableRow>[];
     actions?: TableProps<DocsTableRow>['actions'];
-}) => JSX.Element;
-
-declare const EntityListDocsGrid: () => JSX.Element;
-
-declare function createCopyDocsUrlAction(copyToClipboard: Function): (row: DocsTableRow) => {
-    icon: () => JSX.Element;
-    tooltip: string;
-    onClick: () => any;
 };
-declare function createStarEntityAction(isStarredEntity: Function, toggleStarredEntity: Function): ({ entity }: DocsTableRow) => {
-    cellStyle: {
-        paddingLeft: string;
+/**
+ * Component which renders a table with entities from catalog.
+ *
+ * @public
+ */
+declare const EntityListDocsTable: {
+    (props: EntityListDocsTableProps): JSX.Element;
+    columns: {
+        createNameColumn(): TableColumn<DocsTableRow>;
+        createOwnerColumn(): TableColumn<DocsTableRow>;
+        createTypeColumn(): TableColumn<DocsTableRow>;
+    };
+    actions: {
+        createCopyDocsUrlAction(copyToClipboard: Function): (row: DocsTableRow) => {
+            icon: () => JSX.Element;
+            tooltip: string;
+            onClick: () => any;
+        };
+        createStarEntityAction(isStarredEntity: Function, toggleStarredEntity: Function): ({ entity }: DocsTableRow) => {
+            cellStyle: {
+                paddingLeft: string;
+            };
+            icon: () => JSX.Element;
+            tooltip: string;
+            onClick: () => any;
+        };
     };
-    icon: () => JSX.Element;
-    tooltip: string;
-    onClick: () => any;
 };
 
-declare const actionFactories_createCopyDocsUrlAction: typeof createCopyDocsUrlAction;
-declare const actionFactories_createStarEntityAction: typeof createStarEntityAction;
-declare namespace actionFactories {
-  export {
-    actionFactories_createCopyDocsUrlAction as createCopyDocsUrlAction,
-    actionFactories_createStarEntityAction as createStarEntityAction,
-  };
-}
-
-declare function createNameColumn(): TableColumn<DocsTableRow>;
-declare function createOwnerColumn(): TableColumn<DocsTableRow>;
-declare function createTypeColumn(): TableColumn<DocsTableRow>;
-
-declare const columnFactories_createNameColumn: typeof createNameColumn;
-declare const columnFactories_createOwnerColumn: typeof createOwnerColumn;
-declare const columnFactories_createTypeColumn: typeof createTypeColumn;
-declare namespace columnFactories {
-  export {
-    columnFactories_createNameColumn as createNameColumn,
-    columnFactories_createOwnerColumn as createOwnerColumn,
-    columnFactories_createTypeColumn as createTypeColumn,
-  };
-}
+/**
+ * Props for {@link DocsTable}.
+ *
+ * @public
+ */
+declare type DocsTableProps = {
+    entities: Entity[] | undefined;
+    title?: string | undefined;
+    loading?: boolean | undefined;
+    columns?: TableColumn<DocsTableRow>[];
+    actions?: TableProps<DocsTableRow>['actions'];
+};
+/**
+ * Component which renders a table documents
+ *
+ * @public
+ */
+declare const DocsTable: {
+    (props: DocsTableProps): JSX.Element | null;
+    columns: {
+        createNameColumn(): TableColumn<DocsTableRow>;
+        createOwnerColumn(): TableColumn<DocsTableRow>;
+        createTypeColumn(): TableColumn<DocsTableRow>;
+    };
+    actions: {
+        createCopyDocsUrlAction(copyToClipboard: Function): (row: DocsTableRow) => {
+            icon: () => JSX.Element;
+            tooltip: string;
+            onClick: () => any;
+        };
+        createStarEntityAction(isStarredEntity: Function, toggleStarredEntity: Function): ({ entity }: DocsTableRow) => {
+            cellStyle: {
+                paddingLeft: string;
+            };
+            icon: () => JSX.Element;
+            tooltip: string;
+            onClick: () => any;
+        };
+    };
+};
 
-declare const EntityListDocsTable: {
-    ({ columns, actions, }: {
-        columns?: TableColumn<DocsTableRow>[] | undefined;
-        actions?: TableProps<DocsTableRow>['actions'];
-    }): JSX.Element;
-    columns: typeof columnFactories;
-    actions: typeof actionFactories;
+/**
+ * Props for {@link DefaultTechDocsHome}
+ *
+ * @public
+ */
+declare type DefaultTechDocsHomeProps = {
+    initialFilter?: UserListFilterKind;
+    columns?: TableColumn<DocsTableRow>[];
+    actions?: TableProps<DocsTableRow>['actions'];
 };
+/**
+ * Component which renders a default documentation landing page.
+ *
+ * @public
+ */
+declare const DefaultTechDocsHome: (props: DefaultTechDocsHomeProps) => JSX.Element;
 
+/**
+ * Available panel types
+ *
+ * @public
+ */
 declare type PanelType = 'DocsCardGrid' | 'DocsTable';
+/**
+ * Type representing a TechDocsCustomHome panel.
+ *
+ * @public
+ */
 interface PanelConfig {
     title: string;
     description: string;
@@ -222,30 +416,57 @@ interface PanelConfig {
     panelCSS?: CSSProperties;
     filterPredicate: ((entity: Entity) => boolean) | string;
 }
+/**
+ * Type representing a TechDocsCustomHome tab.
+ *
+ * @public
+ */
 interface TabConfig {
     label: string;
     panels: PanelConfig[];
 }
+/**
+ * Type representing a list of TechDocsCustomHome tabs.
+ *
+ * @public
+ */
 declare type TabsConfig = TabConfig[];
+/**
+ * Props for {@link TechDocsCustomHome}
+ *
+ * @public
+ */
+declare type TechDocsCustomHomeProps = {
+    tabsConfig: TabsConfig;
+};
 
-declare type Props$2 = {
+/**
+ * Props for {@link TechDocsPageWrapper}
+ *
+ * @public
+ */
+declare type TechDocsPageWrapperProps = {
     children?: React.ReactNode;
 };
-declare const TechDocsPageWrapper: ({ children }: Props$2) => JSX.Element;
+/**
+ * Component wrapping a techdocs page with Page and Header components
+ *
+ * @public
+ */
+declare const TechDocsPageWrapper: (props: TechDocsPageWrapperProps) => JSX.Element;
 
+/**
+ * Component responsible for updating TechDocs filters
+ *
+ * @public
+ */
 declare const TechDocsPicker: () => null;
 
-declare type TechDocsPageRenderFunction = ({ techdocsMetadataValue, entityMetadataValue, entityRef, }: {
-    techdocsMetadataValue?: TechDocsMetadata | undefined;
-    entityMetadataValue?: TechDocsEntityMetadata | undefined;
-    entityRef: EntityName;
-    onReady: () => void;
-}) => JSX.Element;
-declare type TechDocsPageProps = {
-    children?: TechDocsPageRenderFunction | React.ReactNode;
-};
-declare const TechDocsPage: ({ children }: TechDocsPageProps) => JSX.Element;
-
+/**
+ * The Backstage plugin that renders technical documentation for your components
+ *
+ * @public
+ */
 declare const techdocsPlugin: _backstage_core_plugin_api.BackstagePlugin<{
     root: _backstage_core_plugin_api.RouteRef<undefined>;
     docRoot: _backstage_core_plugin_api.RouteRef<{
@@ -255,49 +476,54 @@ declare const techdocsPlugin: _backstage_core_plugin_api.BackstagePlugin<{
     }>;
     entityContent: _backstage_core_plugin_api.RouteRef<undefined>;
 }, {}>;
+/**
+ * Routable extension used to render docs
+ *
+ * @public
+ */
 declare const TechdocsPage: () => JSX.Element;
-declare const EntityTechdocsContent: (_props: {
-    entity?: _backstage_catalog_model.Entity | undefined;
-}) => JSX.Element;
-declare const DocsCardGrid: ({ entities, }: {
-    entities: _backstage_catalog_model.Entity[] | undefined;
-}) => JSX.Element | null;
-declare const DocsTable: ({ entities, title, loading, columns, actions, }: {
-    entities: _backstage_catalog_model.Entity[] | undefined;
-    title?: string | undefined;
-    loading?: boolean | undefined;
-    columns?: _backstage_core_components.TableColumn<DocsTableRow>[] | undefined;
-    actions?: (_material_table_core.Action<DocsTableRow> | {
-        action: (rowData: DocsTableRow) => _material_table_core.Action<DocsTableRow>;
-        position: string;
-    } | ((rowData: DocsTableRow) => _material_table_core.Action<DocsTableRow>))[] | undefined;
-}) => JSX.Element | null;
-declare const TechDocsCustomHome: ({ tabsConfig, }: {
-    tabsConfig: TabsConfig;
-}) => JSX.Element;
+/**
+ * Routable extension used to render docs on Entity page
+ *
+ * @public
+ */
+declare const EntityTechdocsContent: () => JSX.Element;
+/**
+ * Component which takes a custom tabs config object and renders a documentation landing page.
+ *
+ * @public
+ */
+declare const TechDocsCustomHome: (props: TechDocsCustomHomeProps) => JSX.Element;
+/**
+ * Responsible for rendering the provided router element
+ *
+ * @public
+ */
 declare const TechDocsIndexPage: () => JSX.Element;
-declare const TechDocsReaderPage: ({ children }: TechDocsPageProps) => JSX.Element;
-
-declare type Props$1 = {
-    entityRef: EntityName;
-    withSearch?: boolean;
-    onReady?: () => void;
-};
-declare const Reader: ({ entityRef, onReady, withSearch, }: Props$1) => JSX.Element;
-
-declare type TechDocsPageHeaderProps = {
-    entityRef: EntityName;
-    entityMetadata?: TechDocsEntityMetadata;
-    techDocsMetadata?: TechDocsMetadata;
-};
-declare const TechDocsPageHeader: ({ entityRef, entityMetadata, techDocsMetadata, }: TechDocsPageHeaderProps) => JSX.Element;
+/**
+ * Component responsible for composing a TechDocs reader page experience
+ *
+ * @public
+ */
+declare const TechDocsReaderPage: (props: TechDocsReaderPageProps) => JSX.Element;
 
+/**
+ * Helper that takes in entity and returns true/false if TechDocs is available for the entity
+ *
+ * @public
+ */
 declare const isTechDocsAvailable: (entity: Entity) => boolean;
+/**
+ * Responsible for registering routes for TechDocs, TechDocs Homepage and separate TechDocs page
+ *
+ * @public
+ */
 declare const Router: () => JSX.Element;
-declare type Props = {
-    /** @deprecated The entity is now grabbed from context instead */
-    entity?: Entity;
-};
-declare const EmbeddedDocsRouter: (_props: Props) => JSX.Element;
+/**
+ * Responsible for registering route to view docs on Entity page
+ *
+ * @public
+ */
+declare const EmbeddedDocsRouter: () => JSX.Element;
 
-export { DefaultTechDocsHome, DocsCardGrid, DocsResultListItem, DocsTable, DocsTableRow, EmbeddedDocsRouter, EntityListDocsGrid, EntityListDocsTable, EntityTechdocsContent, PanelType, Reader, Router, SyncResult, TechDocsApi, TechDocsClient, TechDocsCustomHome, TechDocsIndexPage, TechDocsPage, TechDocsPageHeader, TechDocsPageHeaderProps, TechDocsPageProps, TechDocsPageRenderFunction, TechDocsPageWrapper, TechDocsPicker, TechDocsReaderPage, TechDocsStorageApi, TechDocsStorageClient, TechdocsPage, isTechDocsAvailable, techdocsPlugin as plugin, techdocsApiRef, techdocsPlugin, techdocsStorageApiRef };
+export { DefaultTechDocsHome, DefaultTechDocsHomeProps, DocsCardGrid, DocsCardGridProps, DocsResultListItem, DocsTable, DocsTableProps, DocsTableRow, EmbeddedDocsRouter, EntityListDocsGrid, EntityListDocsTable, EntityListDocsTableProps, EntityTechdocsContent, PanelConfig, PanelType, Reader, ReaderProps, Router, SyncResult, TabConfig, TabsConfig, TechDocsApi, TechDocsClient, TechDocsCustomHome, TechDocsCustomHomeProps, TechDocsEntityMetadata, TechDocsIndexPage, TechDocsMetadata, TechDocsPage, TechDocsPageHeader, TechDocsPageHeaderProps, TechDocsPageRenderFunction, TechDocsPageWrapper, TechDocsPageWrapperProps, TechDocsPicker, TechDocsReaderPage, TechDocsReaderPageHeader, TechDocsReaderPageHeaderProps, TechDocsReaderPageProps, TechDocsReaderPageRenderFunction, TechDocsSearch, TechDocsSearchProps, TechDocsSearchResultListItem, TechDocsSearchResultListItemProps, TechDocsStorageApi, TechDocsStorageClient, TechdocsPage, isTechDocsAvailable, techdocsPlugin as plugin, techdocsApiRef, techdocsPlugin, techdocsStorageApiRef };