From b17958bc6076bb8297517e51886f16635d2f4b1c Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Thu, 17 Feb 2022 11:35:23 +0100 Subject: [PATCH] catalog-react: cleanup api report Signed-off-by: Johan Haals --- plugins/catalog-react/api-report.md | 188 +++++++----------- plugins/catalog-react/src/api.ts | 4 + .../src/components/EntityRefLink/format.ts | 1 + .../EntitySearchBar/EntitySearchBar.tsx | 4 +- .../components/EntityTable/EntityTable.tsx | 2 +- .../FavoriteEntity/FavoriteEntity.tsx | 10 +- .../src/components/FavoriteEntity/index.ts | 1 + .../UnregisterEntityDialog.tsx | 54 ++--- .../UnregisterEntityDialog/index.ts | 1 + .../UserListPicker/UserListPicker.tsx | 10 +- .../src/components/UserListPicker/index.ts | 1 + plugins/catalog-react/src/filters.ts | 27 +++ plugins/catalog-react/src/hooks/index.ts | 7 +- plugins/catalog-react/src/hooks/useEntity.tsx | 4 +- .../src/hooks/useEntityCompoundName.ts | 1 + .../catalog-react/src/hooks/useEntityKinds.ts | 4 +- .../src/hooks/useEntityListProvider.tsx | 13 ++ .../src/hooks/useEntityTypeFilter.tsx | 4 +- plugins/catalog-react/src/hooks/useOwnUser.ts | 1 + .../src/hooks/useRelatedEntities.ts | 1 + .../src/hooks/useStarredEntities.ts | 1 + .../src/hooks/useStarredEntity.ts | 1 + plugins/catalog-react/src/routes.ts | 10 +- .../catalog-react/src/testUtils/providers.tsx | 1 + plugins/catalog-react/src/types.ts | 2 + plugins/catalog-react/src/utils/filters.ts | 2 + .../src/utils/getEntityMetadataUrl.ts | 2 + .../src/utils/getEntityRelations.ts | 1 + .../src/utils/getEntitySourceLocation.ts | 2 + plugins/catalog-react/src/utils/isOwnerOf.ts | 1 + 30 files changed, 202 insertions(+), 159 deletions(-) diff --git a/plugins/catalog-react/api-report.md b/plugins/catalog-react/api-report.md index 5ab3f20d76..4a1b9a9871 100644 --- a/plugins/catalog-react/api-report.md +++ b/plugins/catalog-react/api-report.md @@ -66,9 +66,7 @@ export { CATALOG_FILTER_EXISTS }; export { CatalogApi }; -// Warning: (ae-missing-release-tag) "catalogApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const catalogApiRef: ApiRef; // @public (undocumented) @@ -100,8 +98,6 @@ export type CatalogReactUserListPickerClassKey = | 'menuItem' | 'groupWrapper'; -// Warning: (ae-missing-release-tag) "catalogRouteRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated (undocumented) export const catalogRouteRef: RouteRef; @@ -143,8 +139,6 @@ function createSpecTypeColumn(): TableColumn; // @public (undocumented) function createSystemColumn(): TableColumn; -// Warning: (ae-missing-release-tag) "DefaultEntityFilters" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type DefaultEntityFilters = { kind?: EntityKindFilter; @@ -167,13 +161,9 @@ export class DefaultStarredEntitiesApi implements StarredEntitiesApi { toggleStarred(entityRef: string): Promise; } -// Warning: (ae-forgotten-export) The symbol "EntityLoadingStatus" needs to be exported by the entry point index.d.ts -// // @public @deprecated (undocumented) export const EntityContext: Context; -// Warning: (ae-missing-release-tag) "EntityFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type EntityFilter = { getCatalogFilters?: () => Record< @@ -184,9 +174,7 @@ export type EntityFilter = { toQueryValue?: () => string | string[]; }; -// Warning: (ae-missing-release-tag) "EntityKindFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class EntityKindFilter implements EntityFilter { constructor(value: string); // (undocumented) @@ -210,9 +198,7 @@ export interface EntityKindPickerProps { initialFilter?: string; } -// Warning: (ae-missing-release-tag) "EntityLifecycleFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class EntityLifecycleFilter implements EntityFilter { constructor(values: string[]); // (undocumented) @@ -226,24 +212,42 @@ export class EntityLifecycleFilter implements EntityFilter { // @public (undocumented) export const EntityLifecyclePicker: () => JSX.Element | null; -// Warning: (ae-forgotten-export) The symbol "EntityListContextProps" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "EntityListContext" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const EntityListContext: React_2.Context< EntityListContextProps | undefined >; -// Warning: (ae-missing-release-tag) "EntityListProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) +export type EntityListContextProps< + EntityFilters extends DefaultEntityFilters = DefaultEntityFilters, +> = { + filters: EntityFilters; + entities: Entity[]; + backendEntities: Entity[]; + updateFilters: ( + filters: + | Partial + | ((prevFilters: EntityFilters) => Partial), + ) => void; + queryParameters: Partial>; + loading: boolean; + error?: Error; +}; + +// @public export const EntityListProvider: ({ children, }: PropsWithChildren<{}>) => JSX.Element; -// Warning: (ae-missing-release-tag) "EntityOwnerFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) +export type EntityLoadingStatus = { + entity?: Entity; + loading: boolean; + error?: Error; + refresh?: VoidFunction; +}; + +// @public export class EntityOwnerFilter implements EntityFilter { constructor(values: string[]); // (undocumented) @@ -295,8 +299,6 @@ export type EntityRefLinksProps = { defaultKind?: string; } & Omit; -// Warning: (ae-missing-release-tag) "entityRoute" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated (undocumented) export const entityRoute: RouteRef<{ name: string; @@ -304,17 +306,13 @@ export const entityRoute: RouteRef<{ namespace: string; }>; -// Warning: (ae-missing-release-tag) "entityRouteParams" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function entityRouteParams(entity: Entity): { readonly kind: string; readonly namespace: string; readonly name: string; }; -// Warning: (ae-missing-release-tag) "entityRouteRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const entityRouteRef: RouteRef<{ name: string; @@ -322,11 +320,9 @@ export const entityRouteRef: RouteRef<{ namespace: string; }>; -// @public (undocumented) +// @public export const EntitySearchBar: () => JSX.Element; -// Warning: (ae-missing-release-tag) "EntitySourceLocation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type EntitySourceLocation = { locationTargetUrl: string; @@ -352,8 +348,6 @@ export namespace EntityTable { componentEntityColumns: TableColumn[]; } -// Warning: (ae-unresolved-link) The @link reference could not be resolved: The reference is ambiguous because "EntityTable" has more than one declaration; you need to add a TSDoc member reference selector -// // @public export interface EntityTableProps { // (undocumented) @@ -368,9 +362,7 @@ export interface EntityTableProps { variant?: 'gridItem'; } -// Warning: (ae-missing-release-tag) "EntityTagFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class EntityTagFilter implements EntityFilter { constructor(values: string[]); // (undocumented) @@ -384,9 +376,7 @@ export class EntityTagFilter implements EntityFilter { // @public (undocumented) export const EntityTagPicker: () => JSX.Element | null; -// Warning: (ae-missing-release-tag) "EntityTextFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class EntityTextFilter implements EntityFilter { constructor(value: string); // (undocumented) @@ -395,9 +385,7 @@ export class EntityTextFilter implements EntityFilter { readonly value: string; } -// Warning: (ae-missing-release-tag) "EntityTypeFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class EntityTypeFilter implements EntityFilter { constructor(value: string | string[]); // (undocumented) @@ -423,26 +411,31 @@ export interface EntityTypePickerProps { initialFilter?: string; } -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "FavoriteEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public -export const FavoriteEntity: (props: Props) => JSX.Element; +// @public (undocumented) +export type EntityTypeReturn = { + loading: boolean; + error?: Error; + availableTypes: string[]; + selectedTypes: string[]; + setSelectedTypes: (types: string[]) => void; +}; + +// @public +export const FavoriteEntity: (props: FavoriteEntityProps) => JSX.Element; -// Warning: (ae-missing-release-tag) "favoriteEntityIcon" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const favoriteEntityIcon: (isStarred: boolean) => JSX.Element; -// Warning: (ae-missing-release-tag) "favoriteEntityTooltip" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// +// @public (undocumented) +export type FavoriteEntityProps = ComponentProps & { + entity: Entity; +}; + // @public (undocumented) export const favoriteEntityTooltip: ( isStarred: boolean, ) => 'Remove from favorites' | 'Add to favorites'; -// Warning: (ae-missing-release-tag) "formatEntityRefTitle" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function formatEntityRefTitle( entityRef: Entity | EntityName, @@ -451,18 +444,12 @@ export function formatEntityRefTitle( }, ): string; -// Warning: (ae-missing-release-tag) "getEntityMetadataEditUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function getEntityMetadataEditUrl(entity: Entity): string | undefined; -// Warning: (ae-missing-release-tag) "getEntityMetadataViewUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function getEntityMetadataViewUrl(entity: Entity): string | undefined; -// Warning: (ae-missing-release-tag) "getEntityRelations" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function getEntityRelations( entity: Entity | undefined, @@ -472,8 +459,6 @@ export function getEntityRelations( }, ): EntityName[]; -// Warning: (ae-missing-release-tag) "getEntitySourceLocation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function getEntitySourceLocation( entity: Entity, @@ -487,8 +472,6 @@ export function InspectEntityDialog(props: { onClose: () => void; }): JSX.Element | null; -// Warning: (ae-missing-release-tag) "isOwnerOf" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function isOwnerOf(owner: Entity, owned: Entity): boolean; @@ -503,8 +486,6 @@ export function loadIdentityOwnerRefs( identityApi: IdentityApi, ): Promise; -// Warning: (ae-missing-release-tag) "MockEntityListContextProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const MockEntityListContextProvider: ({ children, @@ -513,22 +494,16 @@ export const MockEntityListContextProvider: ({ value?: Partial> | undefined; }>) => JSX.Element; -// Warning: (ae-missing-release-tag) "reduceCatalogFilters" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function reduceCatalogFilters( filters: EntityFilter[], ): Record; -// Warning: (ae-missing-release-tag) "reduceEntityFilters" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function reduceEntityFilters( filters: EntityFilter[], ): (entity: Entity) => boolean; -// Warning: (ae-missing-release-tag) "rootRoute" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public @deprecated (undocumented) export const rootRoute: RouteRef; @@ -541,16 +516,18 @@ export interface StarredEntitiesApi { // @public export const starredEntitiesApiRef: ApiRef; -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "UnregisterEntityDialog" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) -export const UnregisterEntityDialog: ({ - open, - onConfirm, - onClose, - entity, -}: Props_2) => JSX.Element; +export const UnregisterEntityDialog: ( + props: UnregisterEntityDialogProps, +) => JSX.Element; + +// @public (undocumented) +export type UnregisterEntityDialogProps = { + open: boolean; + onConfirm: () => any; + onClose: () => any; + entity: Entity; +}; // @public export function useEntity(): { @@ -560,8 +537,6 @@ export function useEntity(): { refresh: VoidFunction | undefined; }; -// Warning: (ae-missing-release-tag) "useEntityCompoundName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const useEntityCompoundName: () => { kind: string; @@ -569,23 +544,17 @@ export const useEntityCompoundName: () => { name: string; }; -// Warning: (ae-missing-release-tag) "useEntityFromUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const useEntityFromUrl: () => EntityLoadingStatus; -// Warning: (ae-missing-release-tag) "useEntityKinds" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function useEntityKinds(): { error: Error | undefined; loading: boolean; kinds: string[] | undefined; }; -// Warning: (ae-missing-release-tag) "useEntityListProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function useEntityListProvider< EntityFilters extends DefaultEntityFilters = DefaultEntityFilters, >(): EntityListContextProps; @@ -603,9 +572,6 @@ export function useEntityPermission(permission: Permission): { error?: Error; }; -// Warning: (ae-forgotten-export) The symbol "EntityTypeReturn" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "useEntityTypeFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function useEntityTypeFilter(): EntityTypeReturn; @@ -615,13 +581,9 @@ export function useOwnedEntities(allowedKinds?: string[]): { ownedEntities: GetEntitiesResponse | undefined; }; -// Warning: (ae-missing-release-tag) "useOwnUser" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function useOwnUser(): AsyncState; -// Warning: (ae-missing-release-tag) "useRelatedEntities" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function useRelatedEntities( entity: Entity, @@ -638,9 +600,7 @@ export function useRelatedEntities( error: Error | undefined; }; -// Warning: (ae-missing-release-tag) "UserListFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class UserListFilter implements EntityFilter { constructor( value: UserListFilterKind, @@ -659,22 +619,18 @@ export class UserListFilter implements EntityFilter { readonly value: UserListFilterKind; } -// Warning: (ae-missing-release-tag) "UserListFilterKind" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type UserListFilterKind = 'owned' | 'starred' | 'all'; -// Warning: (ae-forgotten-export) The symbol "UserListPickerProps" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "UserListPicker" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) -export const UserListPicker: ({ - initialFilter, - availableFilters, -}: UserListPickerProps) => JSX.Element; +export const UserListPicker: (props: UserListPickerProps) => JSX.Element; + +// @public (undocumented) +export type UserListPickerProps = { + initialFilter?: UserListFilterKind; + availableFilters?: UserListFilterKind[]; +}; -// Warning: (ae-missing-release-tag) "useStarredEntities" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function useStarredEntities(): { starredEntities: Set; @@ -682,8 +638,6 @@ export function useStarredEntities(): { isStarredEntity: (entityOrRef: Entity | EntityName | string) => boolean; }; -// Warning: (ae-missing-release-tag) "useStarredEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export function useStarredEntity(entityOrRef: Entity | EntityName | string): { toggleStarredEntity: () => void; diff --git a/plugins/catalog-react/src/api.ts b/plugins/catalog-react/src/api.ts index 51146b95bf..38e1f618cd 100644 --- a/plugins/catalog-react/src/api.ts +++ b/plugins/catalog-react/src/api.ts @@ -17,6 +17,10 @@ import { CatalogApi } from '@backstage/catalog-client'; import { createApiRef } from '@backstage/core-plugin-api'; +/** + * The API reference for the {@link @backstage/catalog-client#CatalogApi}. + * @public + */ export const catalogApiRef = createApiRef({ id: 'plugin.catalog.service', }); diff --git a/plugins/catalog-react/src/components/EntityRefLink/format.ts b/plugins/catalog-react/src/components/EntityRefLink/format.ts index 50e018c7ab..90100245a1 100644 --- a/plugins/catalog-react/src/components/EntityRefLink/format.ts +++ b/plugins/catalog-react/src/components/EntityRefLink/format.ts @@ -20,6 +20,7 @@ import { DEFAULT_NAMESPACE, } from '@backstage/catalog-model'; +/** @public */ export function formatEntityRefTitle( entityRef: Entity | EntityName, opts?: { defaultKind?: string }, diff --git a/plugins/catalog-react/src/components/EntitySearchBar/EntitySearchBar.tsx b/plugins/catalog-react/src/components/EntitySearchBar/EntitySearchBar.tsx index ec977fada4..fb7279671f 100644 --- a/plugins/catalog-react/src/components/EntitySearchBar/EntitySearchBar.tsx +++ b/plugins/catalog-react/src/components/EntitySearchBar/EntitySearchBar.tsx @@ -45,7 +45,9 @@ const useStyles = makeStyles( }, ); -/** @public */ +/** + * Renders search bar for filtering the entity list. + * @public */ export const EntitySearchBar = () => { const classes = useStyles(); diff --git a/plugins/catalog-react/src/components/EntityTable/EntityTable.tsx b/plugins/catalog-react/src/components/EntityTable/EntityTable.tsx index 62c33701b4..1248721246 100644 --- a/plugins/catalog-react/src/components/EntityTable/EntityTable.tsx +++ b/plugins/catalog-react/src/components/EntityTable/EntityTable.tsx @@ -22,7 +22,7 @@ import { componentEntityColumns, systemEntityColumns } from './presets'; import { Table, TableColumn } from '@backstage/core-components'; /** - * Props for {@link EntityTable}. + * Props for {@link (EntityTable:function)}. * * @public */ diff --git a/plugins/catalog-react/src/components/FavoriteEntity/FavoriteEntity.tsx b/plugins/catalog-react/src/components/FavoriteEntity/FavoriteEntity.tsx index 730c9a2378..3832a82877 100644 --- a/plugins/catalog-react/src/components/FavoriteEntity/FavoriteEntity.tsx +++ b/plugins/catalog-react/src/components/FavoriteEntity/FavoriteEntity.tsx @@ -21,7 +21,10 @@ import StarBorder from '@material-ui/icons/StarBorder'; import React, { ComponentProps } from 'react'; import { useStarredEntity } from '../../hooks/useStarredEntity'; -type Props = ComponentProps & { entity: Entity }; +/** @public */ +export type FavoriteEntityProps = ComponentProps & { + entity: Entity; +}; const YellowStar = withStyles({ root: { @@ -29,17 +32,20 @@ const YellowStar = withStyles({ }, })(Star); +/** @public */ export const favoriteEntityTooltip = (isStarred: boolean) => isStarred ? 'Remove from favorites' : 'Add to favorites'; +/** @public */ export const favoriteEntityIcon = (isStarred: boolean) => isStarred ? : ; /** * IconButton for showing if a current entity is starred and adding/removing it from the favorite entities * @param props - MaterialUI IconButton props extended by required `entity` prop + * @public */ -export const FavoriteEntity = (props: Props) => { +export const FavoriteEntity = (props: FavoriteEntityProps) => { const { toggleStarredEntity, isStarredEntity } = useStarredEntity( props.entity, ); diff --git a/plugins/catalog-react/src/components/FavoriteEntity/index.ts b/plugins/catalog-react/src/components/FavoriteEntity/index.ts index f731ca7483..a46d04b6c7 100644 --- a/plugins/catalog-react/src/components/FavoriteEntity/index.ts +++ b/plugins/catalog-react/src/components/FavoriteEntity/index.ts @@ -19,3 +19,4 @@ export { favoriteEntityIcon, FavoriteEntity, } from './FavoriteEntity'; +export type { FavoriteEntityProps } from './FavoriteEntity'; diff --git a/plugins/catalog-react/src/components/UnregisterEntityDialog/UnregisterEntityDialog.tsx b/plugins/catalog-react/src/components/UnregisterEntityDialog/UnregisterEntityDialog.tsx index 5c267916ea..48aa2f4012 100644 --- a/plugins/catalog-react/src/components/UnregisterEntityDialog/UnregisterEntityDialog.tsx +++ b/plugins/catalog-react/src/components/UnregisterEntityDialog/UnregisterEntityDialog.tsx @@ -41,13 +41,6 @@ const useStyles = makeStyles({ }, }); -type Props = { - open: boolean; - onConfirm: () => any; - onClose: () => any; - entity: Entity; -}; - const Contents = ({ entity, onConfirm, @@ -248,23 +241,30 @@ const Contents = ({ return Internal error: Unknown state; }; -export const UnregisterEntityDialog = ({ - open, - onConfirm, - onClose, - entity, -}: Props) => ( - - - Are you sure you want to unregister this entity? - - - - - - - - -); +/** @public */ +export type UnregisterEntityDialogProps = { + open: boolean; + onConfirm: () => any; + onClose: () => any; + entity: Entity; +}; + +/** @public */ +export const UnregisterEntityDialog = (props: UnregisterEntityDialogProps) => { + const { open, onConfirm, onClose, entity } = props; + return ( + + + Are you sure you want to unregister this entity? + + + + + + + + + ); +}; diff --git a/plugins/catalog-react/src/components/UnregisterEntityDialog/index.ts b/plugins/catalog-react/src/components/UnregisterEntityDialog/index.ts index 8fc750e706..66eb6961ae 100644 --- a/plugins/catalog-react/src/components/UnregisterEntityDialog/index.ts +++ b/plugins/catalog-react/src/components/UnregisterEntityDialog/index.ts @@ -15,3 +15,4 @@ */ export { UnregisterEntityDialog } from './UnregisterEntityDialog'; +export type { UnregisterEntityDialogProps } from './UnregisterEntityDialog'; diff --git a/plugins/catalog-react/src/components/UserListPicker/UserListPicker.tsx b/plugins/catalog-react/src/components/UserListPicker/UserListPicker.tsx index de23f75e47..3019ae32eb 100644 --- a/plugins/catalog-react/src/components/UserListPicker/UserListPicker.tsx +++ b/plugins/catalog-react/src/components/UserListPicker/UserListPicker.tsx @@ -118,15 +118,15 @@ function getFilterGroups(orgName: string | undefined): ButtonGroup[] { ]; } -type UserListPickerProps = { +/** @public */ +export type UserListPickerProps = { initialFilter?: UserListFilterKind; availableFilters?: UserListFilterKind[]; }; -export const UserListPicker = ({ - initialFilter, - availableFilters, -}: UserListPickerProps) => { +/** @public */ +export const UserListPicker = (props: UserListPickerProps) => { + const { initialFilter, availableFilters } = props; const classes = useStyles(); const configApi = useApi(configApiRef); const orgName = configApi.getOptionalString('organization.name') ?? 'Company'; diff --git a/plugins/catalog-react/src/components/UserListPicker/index.ts b/plugins/catalog-react/src/components/UserListPicker/index.ts index 45cb471197..269c4ca304 100644 --- a/plugins/catalog-react/src/components/UserListPicker/index.ts +++ b/plugins/catalog-react/src/components/UserListPicker/index.ts @@ -15,4 +15,5 @@ */ export { UserListPicker } from './UserListPicker'; +export type { UserListPickerProps } from './UserListPicker'; export type { CatalogReactUserListPickerClassKey } from './UserListPicker'; diff --git a/plugins/catalog-react/src/filters.ts b/plugins/catalog-react/src/filters.ts index 2804d5d6bd..ce8b63f62a 100644 --- a/plugins/catalog-react/src/filters.ts +++ b/plugins/catalog-react/src/filters.ts @@ -19,6 +19,10 @@ import { formatEntityRefTitle } from './components/EntityRefLink'; import { EntityFilter, UserListFilterKind } from './types'; import { getEntityRelations } from './utils'; +/** + * Filter entities based on Kind. + * @public + */ export class EntityKindFilter implements EntityFilter { constructor(readonly value: string) {} @@ -31,6 +35,9 @@ export class EntityKindFilter implements EntityFilter { } } +/** Filters entities based on type + * @public + */ export class EntityTypeFilter implements EntityFilter { constructor(readonly value: string | string[]) {} @@ -48,6 +55,10 @@ export class EntityTypeFilter implements EntityFilter { } } +/** + * Filters entities based on tag. + * @public + */ export class EntityTagFilter implements EntityFilter { constructor(readonly values: string[]) {} @@ -60,6 +71,10 @@ export class EntityTagFilter implements EntityFilter { } } +/** + * Filters entities where the text matches spec, title or tags. + * @public + */ export class EntityTextFilter implements EntityFilter { constructor(readonly value: string) {} @@ -81,6 +96,10 @@ export class EntityTextFilter implements EntityFilter { } } +/** + * Filter matching entities that are owned by group. + * @public + */ export class EntityOwnerFilter implements EntityFilter { constructor(readonly values: string[]) {} @@ -97,6 +116,10 @@ export class EntityOwnerFilter implements EntityFilter { } } +/** + * Filters entities on lifecycle. + * @public + */ export class EntityLifecycleFilter implements EntityFilter { constructor(readonly values: string[]) {} @@ -109,6 +132,10 @@ export class EntityLifecycleFilter implements EntityFilter { } } +/** + * Filters entities based on whatever the user has starred or owns them. + * @public + */ export class UserListFilter implements EntityFilter { constructor( readonly value: UserListFilterKind, diff --git a/plugins/catalog-react/src/hooks/index.ts b/plugins/catalog-react/src/hooks/index.ts index 06791f5706..ba6a1c7341 100644 --- a/plugins/catalog-react/src/hooks/index.ts +++ b/plugins/catalog-react/src/hooks/index.ts @@ -21,6 +21,7 @@ export { AsyncEntityProvider, } from './useEntity'; export type { + EntityLoadingStatus, EntityProviderProps, AsyncEntityProviderProps, } from './useEntity'; @@ -30,8 +31,12 @@ export { EntityListProvider, useEntityListProvider, } from './useEntityListProvider'; -export type { DefaultEntityFilters } from './useEntityListProvider'; +export type { + DefaultEntityFilters, + EntityListContextProps, +} from './useEntityListProvider'; export { useEntityTypeFilter } from './useEntityTypeFilter'; +export type { EntityTypeReturn } from './useEntityTypeFilter'; export { useEntityKinds } from './useEntityKinds'; export { useOwnUser } from './useOwnUser'; export { useRelatedEntities } from './useRelatedEntities'; diff --git a/plugins/catalog-react/src/hooks/useEntity.tsx b/plugins/catalog-react/src/hooks/useEntity.tsx index 6ad61a5d81..8637b820d4 100644 --- a/plugins/catalog-react/src/hooks/useEntity.tsx +++ b/plugins/catalog-react/src/hooks/useEntity.tsx @@ -32,7 +32,8 @@ import useAsyncRetry from 'react-use/lib/useAsyncRetry'; import { catalogApiRef } from '../api'; import { useEntityCompoundName } from './useEntityCompoundName'; -type EntityLoadingStatus = { +/** @public */ +export type EntityLoadingStatus = { entity?: Entity; loading: boolean; error?: Error; @@ -133,6 +134,7 @@ const CompatibilityProvider = ({ }; EntityContext.Provider = CompatibilityProvider as Provider; +/** @public */ export const useEntityFromUrl = (): EntityLoadingStatus => { const { kind, namespace, name } = useEntityCompoundName(); const navigate = useNavigate(); diff --git a/plugins/catalog-react/src/hooks/useEntityCompoundName.ts b/plugins/catalog-react/src/hooks/useEntityCompoundName.ts index 57e1c08a23..75affc98b2 100644 --- a/plugins/catalog-react/src/hooks/useEntityCompoundName.ts +++ b/plugins/catalog-react/src/hooks/useEntityCompoundName.ts @@ -18,6 +18,7 @@ import { useRouteRefParams } from '@backstage/core-plugin-api'; /** * Grabs entity kind, namespace, and name from the location + * @public */ export const useEntityCompoundName = () => { const { kind, namespace, name } = useRouteRefParams(entityRouteRef); diff --git a/plugins/catalog-react/src/hooks/useEntityKinds.ts b/plugins/catalog-react/src/hooks/useEntityKinds.ts index 1d5b2fec52..6bd39be3c8 100644 --- a/plugins/catalog-react/src/hooks/useEntityKinds.ts +++ b/plugins/catalog-react/src/hooks/useEntityKinds.ts @@ -18,7 +18,9 @@ import useAsync from 'react-use/lib/useAsync'; import { useApi } from '@backstage/core-plugin-api'; import { catalogApiRef } from '../api'; -// Retrieve a list of unique entity kinds present in the catalog +/** Retrieve a list of unique entity kinds present in the catalog + * @public + */ export function useEntityKinds() { const catalogApi = useApi(catalogApiRef); diff --git a/plugins/catalog-react/src/hooks/useEntityListProvider.tsx b/plugins/catalog-react/src/hooks/useEntityListProvider.tsx index 9b4d850208..0dda80be12 100644 --- a/plugins/catalog-react/src/hooks/useEntityListProvider.tsx +++ b/plugins/catalog-react/src/hooks/useEntityListProvider.tsx @@ -43,6 +43,7 @@ import { EntityFilter } from '../types'; import { reduceCatalogFilters, reduceEntityFilters } from '../utils'; import { useApi } from '@backstage/core-plugin-api'; +/** @public */ export type DefaultEntityFilters = { kind?: EntityKindFilter; type?: EntityTypeFilter; @@ -53,6 +54,7 @@ export type DefaultEntityFilters = { text?: EntityTextFilter; }; +/** @public */ export type EntityListContextProps< EntityFilters extends DefaultEntityFilters = DefaultEntityFilters, > = { @@ -91,6 +93,10 @@ export type EntityListContextProps< error?: Error; }; +/** + * Creates new context for entity listing and filtering. + * @public + */ export const EntityListContext = createContext< EntityListContextProps | undefined >(undefined); @@ -101,6 +107,9 @@ type OutputState = { backendEntities: Entity[]; }; +/** + * Provides entities and filters for a catalog listing. + * @public */ export const EntityListProvider = ({ children, }: PropsWithChildren<{}>) => { @@ -239,6 +248,10 @@ export const EntityListProvider = ({ ); }; +/** + * Hook for interacting with the entity list context provided by the {@link EntityListProvider}. + * @public + */ export function useEntityListProvider< EntityFilters extends DefaultEntityFilters = DefaultEntityFilters, >(): EntityListContextProps { diff --git a/plugins/catalog-react/src/hooks/useEntityTypeFilter.tsx b/plugins/catalog-react/src/hooks/useEntityTypeFilter.tsx index c4531d9117..8e5be53950 100644 --- a/plugins/catalog-react/src/hooks/useEntityTypeFilter.tsx +++ b/plugins/catalog-react/src/hooks/useEntityTypeFilter.tsx @@ -22,7 +22,8 @@ import { catalogApiRef } from '../api'; import { useEntityListProvider } from './useEntityListProvider'; import { EntityTypeFilter } from '../filters'; -type EntityTypeReturn = { +/** @public */ +export type EntityTypeReturn = { loading: boolean; error?: Error; availableTypes: string[]; @@ -33,6 +34,7 @@ type EntityTypeReturn = { /** * A hook built on top of `useEntityListProvider` for enabling selection of valid `spec.type` values * based on the selected EntityKindFilter. + * @public */ export function useEntityTypeFilter(): EntityTypeReturn { const catalogApi = useApi(catalogApiRef); diff --git a/plugins/catalog-react/src/hooks/useOwnUser.ts b/plugins/catalog-react/src/hooks/useOwnUser.ts index 497f065f04..1477de67aa 100644 --- a/plugins/catalog-react/src/hooks/useOwnUser.ts +++ b/plugins/catalog-react/src/hooks/useOwnUser.ts @@ -25,6 +25,7 @@ import { identityApiRef, useApi } from '@backstage/core-plugin-api'; /** * Get the catalog User entity (if any) that matches the logged-in user. + * @public */ export function useOwnUser(): AsyncState { const catalogApi = useApi(catalogApiRef); diff --git a/plugins/catalog-react/src/hooks/useRelatedEntities.ts b/plugins/catalog-react/src/hooks/useRelatedEntities.ts index 942941e3d5..56dfbe6403 100644 --- a/plugins/catalog-react/src/hooks/useRelatedEntities.ts +++ b/plugins/catalog-react/src/hooks/useRelatedEntities.ts @@ -21,6 +21,7 @@ import { catalogApiRef } from '../api'; const BATCH_SIZE = 20; +/** @public */ export function useRelatedEntities( entity: Entity, { type, kind }: { type?: string; kind?: string }, diff --git a/plugins/catalog-react/src/hooks/useStarredEntities.ts b/plugins/catalog-react/src/hooks/useStarredEntities.ts index 066040bf02..5ddabfdd2e 100644 --- a/plugins/catalog-react/src/hooks/useStarredEntities.ts +++ b/plugins/catalog-react/src/hooks/useStarredEntities.ts @@ -30,6 +30,7 @@ function getEntityRef(entityOrRef: Entity | EntityName | string): string { : stringifyEntityRef(entityOrRef); } +/** @public */ export function useStarredEntities(): { starredEntities: Set; toggleStarredEntity: (entityOrRef: Entity | EntityName | string) => void; diff --git a/plugins/catalog-react/src/hooks/useStarredEntity.ts b/plugins/catalog-react/src/hooks/useStarredEntity.ts index 0233432196..2c647163aa 100644 --- a/plugins/catalog-react/src/hooks/useStarredEntity.ts +++ b/plugins/catalog-react/src/hooks/useStarredEntity.ts @@ -29,6 +29,7 @@ function getEntityRef(entityOrRef: Entity | EntityName | string): string { : stringifyEntityRef(entityOrRef); } +/** @public */ export function useStarredEntity(entityOrRef: Entity | EntityName | string): { toggleStarredEntity: () => void; isStarredEntity: boolean; diff --git a/plugins/catalog-react/src/routes.ts b/plugins/catalog-react/src/routes.ts index 57801fab4a..b9aa0de531 100644 --- a/plugins/catalog-react/src/routes.ts +++ b/plugins/catalog-react/src/routes.ts @@ -21,6 +21,7 @@ import { getOrCreateGlobalSingleton } from '@backstage/version-bridge'; // TODO(Rugvip): Move these route refs back to the catalog plugin once we're all ported to using external routes /** * @deprecated Use an `ExternalRouteRef` instead, which can point to `catalogPlugin.routes.catalogIndex`. + * @public */ export const rootRoute = createRouteRef({ id: 'catalog', @@ -28,6 +29,7 @@ export const rootRoute = createRouteRef({ /** * @deprecated Use an `ExternalRouteRef` instead, which can point to `catalogPlugin.routes.catalogIndex`. + * @public */ export const catalogRouteRef = rootRoute; @@ -39,6 +41,7 @@ export const catalogRouteRef = rootRoute; * * If you want to replace the `EntityPage` from `@backstage/catalog-plugin` in your app, * you need to use the `entityRouteRef` as the mount point instead of your own. + * @public */ export const entityRouteRef = getOrCreateGlobalSingleton( 'catalog:entity-route-ref', @@ -51,11 +54,14 @@ export const entityRouteRef = getOrCreateGlobalSingleton( /** * @deprecated use `entityRouteRef` instead. + * @public */ export const entityRoute = entityRouteRef; -// Utility function to get suitable route params for entityRoute, given an -// entity instance +/** + * Utility function to get suitable route params for entityRoute, given an + * @public + */ export function entityRouteParams(entity: Entity) { return { kind: entity.kind.toLocaleLowerCase('en-US'), diff --git a/plugins/catalog-react/src/testUtils/providers.tsx b/plugins/catalog-react/src/testUtils/providers.tsx index 3fb295298c..5867026a8c 100644 --- a/plugins/catalog-react/src/testUtils/providers.tsx +++ b/plugins/catalog-react/src/testUtils/providers.tsx @@ -26,6 +26,7 @@ import { EntityListContextProps, } from '../hooks/useEntityListProvider'; +/** @public */ export const MockEntityListContextProvider = ({ children, value, diff --git a/plugins/catalog-react/src/types.ts b/plugins/catalog-react/src/types.ts index 964858cb10..440bab2b22 100644 --- a/plugins/catalog-react/src/types.ts +++ b/plugins/catalog-react/src/types.ts @@ -16,6 +16,7 @@ import { Entity } from '@backstage/catalog-model'; +/** @public */ export type EntityFilter = { /** * Get filters to add to the catalog-backend request. These are a dot-delimited field with @@ -43,4 +44,5 @@ export type EntityFilter = { toQueryValue?: () => string | string[]; }; +/** @public */ export type UserListFilterKind = 'owned' | 'starred' | 'all'; diff --git a/plugins/catalog-react/src/utils/filters.ts b/plugins/catalog-react/src/utils/filters.ts index 109e864c52..d64a821df7 100644 --- a/plugins/catalog-react/src/utils/filters.ts +++ b/plugins/catalog-react/src/utils/filters.ts @@ -17,6 +17,7 @@ import { Entity } from '@backstage/catalog-model'; import { EntityFilter } from '../types'; +/** @public */ export function reduceCatalogFilters( filters: EntityFilter[], ): Record { @@ -28,6 +29,7 @@ export function reduceCatalogFilters( }, {} as Record); } +/** @public */ export function reduceEntityFilters( filters: EntityFilter[], ): (entity: Entity) => boolean { diff --git a/plugins/catalog-react/src/utils/getEntityMetadataUrl.ts b/plugins/catalog-react/src/utils/getEntityMetadataUrl.ts index 3b44816ac1..a5cef7d71e 100644 --- a/plugins/catalog-react/src/utils/getEntityMetadataUrl.ts +++ b/plugins/catalog-react/src/utils/getEntityMetadataUrl.ts @@ -20,10 +20,12 @@ import { Entity, } from '@backstage/catalog-model'; +/** @public */ export function getEntityMetadataViewUrl(entity: Entity): string | undefined { return entity.metadata.annotations?.[ANNOTATION_VIEW_URL]; } +/** @public */ export function getEntityMetadataEditUrl(entity: Entity): string | undefined { return entity.metadata.annotations?.[ANNOTATION_EDIT_URL]; } diff --git a/plugins/catalog-react/src/utils/getEntityRelations.ts b/plugins/catalog-react/src/utils/getEntityRelations.ts index 0045fac4f5..25666a9960 100644 --- a/plugins/catalog-react/src/utils/getEntityRelations.ts +++ b/plugins/catalog-react/src/utils/getEntityRelations.ts @@ -18,6 +18,7 @@ import { Entity, EntityName } from '@backstage/catalog-model'; /** * Get the related entity references. + * @public */ export function getEntityRelations( entity: Entity | undefined, diff --git a/plugins/catalog-react/src/utils/getEntitySourceLocation.ts b/plugins/catalog-react/src/utils/getEntitySourceLocation.ts index dd4d5c07f6..d2141449a8 100644 --- a/plugins/catalog-react/src/utils/getEntitySourceLocation.ts +++ b/plugins/catalog-react/src/utils/getEntitySourceLocation.ts @@ -21,11 +21,13 @@ import { } from '@backstage/catalog-model'; import { ScmIntegrationRegistry } from '@backstage/integration'; +/** @public */ export type EntitySourceLocation = { locationTargetUrl: string; integrationType?: string; }; +/** @public */ export function getEntitySourceLocation( entity: Entity, scmIntegrationsApi: ScmIntegrationRegistry, diff --git a/plugins/catalog-react/src/utils/isOwnerOf.ts b/plugins/catalog-react/src/utils/isOwnerOf.ts index 38ad90e4a6..3ef6b4b2a0 100644 --- a/plugins/catalog-react/src/utils/isOwnerOf.ts +++ b/plugins/catalog-react/src/utils/isOwnerOf.ts @@ -25,6 +25,7 @@ import { getEntityRelations } from './getEntityRelations'; /** * Get the related entity references. + * @public */ export function isOwnerOf(owner: Entity, owned: Entity) { const possibleOwners = new Set(