diff --git a/plugins/home/api-report.md b/plugins/home/api-report.md index 14f685cfc1..09b1be16ba 100644 --- a/plugins/home/api-report.md +++ b/plugins/home/api-report.md @@ -11,9 +11,11 @@ import { CardConfig as CardConfig_2 } from '@backstage/plugin-home-react'; import { CardExtensionProps as CardExtensionProps_2 } from '@backstage/plugin-home-react'; import { CardLayout as CardLayout_2 } from '@backstage/plugin-home-react'; import { CardSettings as CardSettings_2 } from '@backstage/plugin-home-react'; +import { ClassNameMap } from '@material-ui/styles'; import { ComponentParts as ComponentParts_2 } from '@backstage/plugin-home-react'; import { ComponentRenderer as ComponentRenderer_2 } from '@backstage/plugin-home-react'; import { createCardExtension as createCardExtension_2 } from '@backstage/plugin-home-react'; +import { EntityFilterQuery } from '@backstage/catalog-client'; import { ErrorApi } from '@backstage/core-plugin-api'; import { IdentityApi } from '@backstage/core-plugin-api'; import { JSX as JSX_2 } from 'react'; @@ -101,6 +103,21 @@ export type CustomHomepageGridProps = { preventCollision?: boolean; }; +// @public +export const FeaturedDocs: (props: FeaturedDocsProps) => JSX_2.Element; + +// @public +export type FeaturedDocsProps = { + filter: EntityFilterQuery; + color?: 'inherit' | 'primary' | 'secondary' | undefined; + customStyles?: ClassNameMap | undefined; + emptyState?: React_2.ReactNode | undefined; + path?: string | undefined; + responseLimit?: number | undefined; + subLinkText?: string | undefined; + title?: React_2.ReactNode | string | undefined; +}; + // @public export const HeaderWorldClock: (props: { clockConfigs: ClockConfig[]; diff --git a/plugins/home/src/homePageComponents/FeaturedDocs/FeaturedDocs.tsx b/plugins/home/src/homePageComponents/FeaturedDocs/FeaturedDocs.tsx index 459dc7bdb6..7b1f3f9d3e 100644 --- a/plugins/home/src/homePageComponents/FeaturedDocs/FeaturedDocs.tsx +++ b/plugins/home/src/homePageComponents/FeaturedDocs/FeaturedDocs.tsx @@ -20,10 +20,9 @@ import { LinkButton, EmptyState, Link, - CodeSnippet, InfoCard, Progress, - WarningPanel, + ErrorPanel, } from '@backstage/core-components'; import { catalogApiRef, CatalogApi } from '@backstage/plugin-catalog-react'; import { useApi } from '@backstage/core-plugin-api'; @@ -32,21 +31,36 @@ import { ClassNameMap } from '@material-ui/styles'; import { makeStyles, Theme, Typography } from '@material-ui/core'; -type DocsCardProps = { +/** + * Props customizing the component. + * + * @public + */ +export type FeaturedDocsProps = { + /** The entity filter used to display only the intended item/s */ filter: EntityFilterQuery; + /** An optional color which can be customized through themes */ color?: 'inherit' | 'primary' | 'secondary' | undefined; + /** An optional ClassNameMap created with makeStyles */ customStyles?: ClassNameMap | undefined; + /** An optional ReactNode for empty states */ emptyState?: React.ReactNode | undefined; + /** An optional path to set for entity entry */ + path?: string | undefined; + /** An optional limit to set for link destination */ + responseLimit?: number | undefined; + /** An optional string to customize sublink text */ subLinkText?: string | undefined; + /** An optional string or ReactNode to customize the card title */ title?: React.ReactNode | string | undefined; }; -const useStyles = makeStyles(() => ({ +const useStyles = makeStyles(theme => ({ docDescription: { fontSize: 16, fontWeight: 400, - marginBottom: '16px', - marginTop: '12px', + marginBottom: theme.spacing(2), + marginTop: theme.spacing(2), }, docSubLink: { fontSize: 12, @@ -62,17 +76,20 @@ const useStyles = makeStyles(() => ({ /** * A component to display specific Featured Docs. - * @param {EntityFilterQuery} filter - The entity filter used to display only the intended item/s - * @param {'inherit' | 'primary' | 'secondary' | undefined} [color] - An optional color which can be customized through themes - * @param {ClassNameMap | undefined} [customStyles] - An optional ClassNameMap created with makeStyles - * @param {React.ReactNode | undefined} [emptyState] - An optional ReactNode for empty states - * @param {string | undefined} [subLinkText] - An optional string to customize sublink text - * @param {React.ReactNode | string | undefined} [title] - An optional string or ReactNode to customize the card title * * @public */ -export const FeaturedDocs = (props: DocsCardProps) => { - const { color, customStyles, emptyState, filter, subLinkText, title } = props; +export const FeaturedDocs = (props: FeaturedDocsProps) => { + const { + color, + customStyles, + emptyState, + filter, + path, + responseLimit, + subLinkText, + title, + } = props; const linkText = subLinkText || 'LEARN MORE'; const defaultStyles = useStyles(); const styles = customStyles || defaultStyles; @@ -84,27 +101,15 @@ export const FeaturedDocs = (props: DocsCardProps) => { } = useAsync(async () => { const response = await catalogApi.getEntities({ filter: filter, + limit: responseLimit || 10, }); return response.items; }); - if (loading) { - return ; - } - - if (error) { - return ( - - - - ); - } - return ( + {loading && } + {error && } {entities?.length ? entities.map(d => (
@@ -112,9 +117,12 @@ export const FeaturedDocs = (props: DocsCardProps) => { className={styles.docsTitleLink} data-testid="docs-card-title" color={color || 'primary'} - to={`/docs/${d.metadata.namespace || 'default'}/${d.kind}/${ - d.metadata.name - }/`} + to={ + path || + `/docs/${d.metadata.namespace || 'default'}/${d.kind}/${ + d.metadata.name + }/` + } > {d.metadata.title} @@ -125,9 +133,12 @@ export const FeaturedDocs = (props: DocsCardProps) => { className={styles.docSubLink} data-testid="docs-card-sub-link" color={color || 'primary'} - to={`/docs/${d.metadata.namespace || 'default'}/${d.kind}/${ - d.metadata.name - }/`} + to={ + path || + `/docs/${d.metadata.namespace || 'default'}/${d.kind}/${ + d.metadata.name + }/` + } > {linkText} diff --git a/plugins/home/src/homePageComponents/FeaturedDocs/index.ts b/plugins/home/src/homePageComponents/FeaturedDocs/index.ts index 08ca030dca..b4efed3268 100644 --- a/plugins/home/src/homePageComponents/FeaturedDocs/index.ts +++ b/plugins/home/src/homePageComponents/FeaturedDocs/index.ts @@ -15,3 +15,4 @@ */ export { FeaturedDocs } from './FeaturedDocs'; +export type { FeaturedDocsProps } from './FeaturedDocs'; diff --git a/plugins/home/src/homePageComponents/index.ts b/plugins/home/src/homePageComponents/index.ts index 9149afa295..b3c7d77c46 100644 --- a/plugins/home/src/homePageComponents/index.ts +++ b/plugins/home/src/homePageComponents/index.ts @@ -18,3 +18,4 @@ export type { ToolkitContentProps, Tool } from './Toolkit'; export type { ClockConfig } from './HeaderWorldClock'; export type { WelcomeTitleLanguageProps } from './WelcomeTitle'; export type { VisitedByTypeProps, VisitedByTypeKind } from './VisitedByType'; +export type { FeaturedDocsProps } from './FeaturedDocs';