From 7bb1bde7f63354a6edd2448ec020e54d13d4c10a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Thu, 3 Feb 2022 15:53:26 +0100 Subject: [PATCH] Bunch of random api cleanup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/wise-peaches-flow.md | 8 + .../api-report.md | 10 +- .../src/microsoftGraph/index.ts | 3 +- plugins/catalog-graph/api-report.md | 4 - .../components/EntityRelationsGraph/types.ts | 7 +- plugins/catalog-import/api-report.md | 368 ++++++++++++------ .../src/api/CatalogImportApi.ts | 17 +- .../src/api/CatalogImportClient.ts | 49 ++- .../DefaultImportPage/DefaultImportPage.tsx | 5 + .../EntityListComponent.tsx | 32 +- .../components/EntityListComponent/index.ts | 1 + .../ImportInfoCard/ImportInfoCard.tsx | 24 +- .../src/components/ImportInfoCard/index.ts | 1 + .../src/components/ImportPage/ImportPage.tsx | 5 + .../ImportStepper/ImportStepper.tsx | 26 +- .../src/components/ImportStepper/defaults.tsx | 10 +- .../src/components/ImportStepper/index.ts | 1 + .../StepInitAnalyzeUrl/StepInitAnalyzeUrl.tsx | 24 +- .../components/StepInitAnalyzeUrl/index.ts | 1 + .../AutocompleteTextField.tsx | 42 +- .../PreparePullRequestForm.tsx | 23 +- .../PreviewCatalogInfoComponent.tsx | 23 +- .../PreviewPullRequestComponent.tsx | 23 +- .../StepPrepareCreatePullRequest.tsx | 25 +- .../StepPrepareCreatePullRequest/index.ts | 5 + .../catalog-import/src/components/index.ts | 1 + .../src/components/useImportState.ts | 12 +- plugins/catalog-import/src/plugin.ts | 11 + plugins/catalog-react/api-report.md | 124 +++--- .../EntityKindPicker/EntityKindPicker.tsx | 17 +- .../src/components/EntityKindPicker/index.ts | 1 + .../EntityLifecyclePicker.tsx | 1 + .../EntityOwnerPicker/EntityOwnerPicker.tsx | 1 + .../EntityRefLink/EntityRefLink.tsx | 11 + .../EntityRefLink/EntityRefLinks.tsx | 11 + .../src/components/EntityRefLink/index.ts | 3 + .../EntitySearchBar/EntitySearchBar.tsx | 1 + .../components/EntityTable/EntityTable.tsx | 31 +- .../src/components/EntityTable/columns.tsx | 15 +- .../src/components/EntityTable/index.ts | 2 + .../EntityTagPicker/EntityTagPicker.tsx | 1 + .../EntityTypePicker/EntityTypePicker.tsx | 12 +- .../src/components/EntityTypePicker/index.ts | 2 +- plugins/catalog-react/src/components/index.ts | 1 + scripts/api-extractor.ts | 2 + 45 files changed, 670 insertions(+), 327 deletions(-) create mode 100644 .changeset/wise-peaches-flow.md diff --git a/.changeset/wise-peaches-flow.md b/.changeset/wise-peaches-flow.md new file mode 100644 index 0000000000..68e89cf841 --- /dev/null +++ b/.changeset/wise-peaches-flow.md @@ -0,0 +1,8 @@ +--- +'@backstage/plugin-catalog-backend-module-msgraph': patch +'@backstage/plugin-catalog-graph': patch +'@backstage/plugin-catalog-import': patch +'@backstage/plugin-catalog-react': patch +--- + +Minor API cleanups diff --git a/plugins/catalog-backend-module-msgraph/api-report.md b/plugins/catalog-backend-module-msgraph/api-report.md index 662056eff1..c00930d2ce 100644 --- a/plugins/catalog-backend-module-msgraph/api-report.md +++ b/plugins/catalog-backend-module-msgraph/api-report.md @@ -33,6 +33,15 @@ export function defaultUserTransformer( userPhoto?: string, ): Promise; +// @public +export type GroupMember = + | (MicrosoftGraph.Group & { + '@odata.type': '#microsoft.graph.user'; + }) + | (MicrosoftGraph.User & { + '@odata.type': '#microsoft.graph.group'; + }); + // @public export type GroupTransformer = ( group: MicrosoftGraph.Group, @@ -54,7 +63,6 @@ export const MICROSOFT_GRAPH_USER_ID_ANNOTATION = 'graph.microsoft.com/user-id'; export class MicrosoftGraphClient { constructor(baseUrl: string, pca: msal.ConfidentialClientApplication); static create(config: MicrosoftGraphProviderConfig): MicrosoftGraphClient; - // Warning: (ae-forgotten-export) The symbol "GroupMember" needs to be exported by the entry point index.d.ts getGroupMembers(groupId: string): AsyncIterable; // (undocumented) getGroupPhoto(groupId: string, sizeId?: string): Promise; diff --git a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/index.ts b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/index.ts index b0d53b43a2..61e62f5803 100644 --- a/plugins/catalog-backend-module-msgraph/src/microsoftGraph/index.ts +++ b/plugins/catalog-backend-module-msgraph/src/microsoftGraph/index.ts @@ -13,8 +13,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + export { MicrosoftGraphClient } from './client'; -export type { ODataQuery } from './client'; +export type { GroupMember, ODataQuery } from './client'; export { readMicrosoftGraphConfig } from './config'; export type { MicrosoftGraphProviderConfig } from './config'; export { diff --git a/plugins/catalog-graph/api-report.md b/plugins/catalog-graph/api-report.md index e39982d2b5..515a578d3c 100644 --- a/plugins/catalog-graph/api-report.md +++ b/plugins/catalog-graph/api-report.md @@ -95,8 +95,6 @@ export const EntityCatalogGraphCard: ({ // @public export type EntityEdge = DependencyGraphTypes.DependencyEdge; -// Warning: (ae-missing-release-tag) "EntityEdgeData" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityEdgeData = { relations: string[]; @@ -106,8 +104,6 @@ export type EntityEdgeData = { // @public export type EntityNode = DependencyGraphTypes.DependencyNode; -// Warning: (ae-missing-release-tag) "EntityNodeData" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type EntityNodeData = { name: string; diff --git a/plugins/catalog-graph/src/components/EntityRelationsGraph/types.ts b/plugins/catalog-graph/src/components/EntityRelationsGraph/types.ts index 830032d527..caf6c8c501 100644 --- a/plugins/catalog-graph/src/components/EntityRelationsGraph/types.ts +++ b/plugins/catalog-graph/src/components/EntityRelationsGraph/types.ts @@ -13,11 +13,14 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + import { DependencyGraphTypes } from '@backstage/core-components'; import { MouseEventHandler } from 'react'; /** - * Additional Data for entities + * Additional Data for entities. + * + * @public */ export type EntityEdgeData = { /** @@ -40,6 +43,8 @@ export type EntityEdge = DependencyGraphTypes.DependencyEdge; /** * Additional data for Entity Node + * + * @public */ export type EntityNodeData = { /** diff --git a/plugins/catalog-import/api-report.md b/plugins/catalog-import/api-report.md index a85777c563..164d831c96 100644 --- a/plugins/catalog-import/api-report.md +++ b/plugins/catalog-import/api-report.md @@ -26,9 +26,7 @@ import { UnpackNestedValue } from 'react-hook-form'; import { UseFormProps } from 'react-hook-form'; import { UseFormReturn } from 'react-hook-form'; -// Warning: (ae-missing-release-tag) "AnalyzeResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type AnalyzeResult = | { type: 'locations'; @@ -45,26 +43,36 @@ export type AnalyzeResult = generatedEntities: PartialEntity[]; }; -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "AutocompleteTextField" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const AutocompleteTextField: ({ - name, - options, - required, - errors, - rules, - loading, - loadingText, - helperText, - errorHelperText, - textFieldProps, -}: Props_5) => JSX.Element; +// @public +export const AutocompleteTextField: ( + props: AutocompleteTextFieldProps, +) => JSX.Element; -// Warning: (ae-missing-release-tag) "CatalogImportApi" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export interface AutocompleteTextFieldProps { + // (undocumented) + errorHelperText?: string; + // (undocumented) + errors?: FieldErrors; + // (undocumented) + helperText?: React_2.ReactNode; + // (undocumented) + loading?: boolean; + // (undocumented) + loadingText?: string; + // (undocumented) + name: TFieldValue; + // (undocumented) + options: string[]; + // (undocumented) + required?: boolean; + // (undocumented) + rules?: React_2.ComponentProps['rules']; + // (undocumented) + textFieldProps?: Omit; +} + +// @public export interface CatalogImportApi { // (undocumented) analyzeUrl(url: string): Promise; @@ -85,14 +93,10 @@ export interface CatalogImportApi { }>; } -// Warning: (ae-missing-release-tag) "catalogImportApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const catalogImportApiRef: ApiRef; -// Warning: (ae-missing-release-tag) "CatalogImportClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class CatalogImportClient implements CatalogImportApi { constructor(options: { discoveryApi: DiscoveryApi; @@ -110,12 +114,7 @@ export class CatalogImportClient implements CatalogImportApi { body: string; }>; // (undocumented) - submitPullRequest({ - repositoryUrl, - fileContent, - title, - body, - }: { + submitPullRequest(options: { repositoryUrl: string; fileContent: string; title: string; @@ -126,14 +125,10 @@ export class CatalogImportClient implements CatalogImportApi { }>; } -// Warning: (ae-missing-release-tag) "CatalogImportPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const CatalogImportPage: () => JSX.Element; -// Warning: (ae-missing-release-tag) "catalogImportPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public const catalogImportPlugin: BackstagePlugin< { importPage: RouteRef; @@ -143,9 +138,7 @@ const catalogImportPlugin: BackstagePlugin< export { catalogImportPlugin }; export { catalogImportPlugin as plugin }; -// Warning: (ae-forgotten-export) The symbol "ImportFlows" needs to be exported by the entry point index.d.ts // Warning: (ae-forgotten-export) The symbol "StepperProvider" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "defaultGenerateStepper" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public export function defaultGenerateStepper( @@ -153,98 +146,221 @@ export function defaultGenerateStepper( defaults: StepperProvider, ): StepperProvider; -// Warning: (ae-missing-release-tag) "DefaultImportPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const DefaultImportPage: () => JSX.Element; -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "EntityListComponent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const EntityListComponent: ({ - locations, - collapsed, - locationListItemIcon, - onItemClick, - firstListItem, - withLinks, -}: Props) => JSX.Element; - -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "ImportInfoCard" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const ImportInfoCard: ({ - exampleLocationUrl, - exampleRepositoryUrl, -}: Props_2) => JSX.Element; - -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "ImportStepper" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const ImportStepper: ({ - initialUrl, - generateStepper, - variant, -}: Props_3) => JSX.Element; - -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "PreparePullRequestForm" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public -export const PreparePullRequestForm: < +export const EntityListComponent: ( + props: EntityListComponentProps, +) => JSX.Element; + +// @public +export interface EntityListComponentProps { + // (undocumented) + collapsed?: boolean; + // (undocumented) + firstListItem?: React_2.ReactElement; + // (undocumented) + locationListItemIcon: (target: string) => React_2.ReactElement; + // (undocumented) + locations: Array<{ + target: string; + entities: (Entity | EntityName)[]; + }>; + // (undocumented) + onItemClick?: (target: string) => void; + // (undocumented) + withLinks?: boolean; +} + +// @public +export type ImportFlows = + | 'unknown' + | 'single-location' + | 'multiple-locations' + | 'no-location'; + +// @public +export const ImportInfoCard: (props: ImportInfoCardProps) => JSX.Element; + +// @public +export interface ImportInfoCardProps { + // (undocumented) + exampleLocationUrl?: string; + // (undocumented) + exampleRepositoryUrl?: string; +} + +// Warning: (ae-forgotten-export) The symbol "State" needs to be exported by the entry point index.d.ts +// Warning: (ae-missing-release-tag) "ImportState" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export type ImportState = State & { + activeFlow: ImportFlows; + activeStepNumber: number; + analysisUrl?: string; + onGoBack?: () => void; + onReset: () => void; +}; + +// @public +export const ImportStepper: (props: ImportStepperProps) => JSX.Element; + +// @public +export interface ImportStepperProps { + // (undocumented) + generateStepper?: ( + flow: ImportFlows, + defaults: StepperProvider, + ) => StepperProvider; + // (undocumented) + initialUrl?: string; + // (undocumented) + variant?: InfoCardVariants; +} + +// @public +export const PreparePullRequestForm: >( + props: PreparePullRequestFormProps, +) => JSX.Element; + +// @public +export type PreparePullRequestFormProps< TFieldValues extends Record, ->({ - defaultValues, - onSubmit, - render, -}: Props_6) => JSX.Element; +> = Pick, 'defaultValues'> & { + onSubmit: SubmitHandler; + render: ( + props: Pick< + UseFormReturn, + 'formState' | 'register' | 'control' | 'setValue' + > & { + values: UnpackNestedValue; + }, + ) => React_2.ReactNode; +}; -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "PreviewCatalogInfoComponent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const PreviewCatalogInfoComponent: ({ - repositoryUrl, - entities, - classes, -}: Props_7) => JSX.Element; - -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "PreviewPullRequestComponent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const PreviewPullRequestComponent: ({ - title, - description, - classes, -}: Props_8) => JSX.Element; - -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "StepInitAnalyzeUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public -export const StepInitAnalyzeUrl: ({ - onAnalysis, - analysisUrl, - disablePullRequest, - exampleLocationUrl, -}: Props_4) => JSX.Element; +export type PrepareResult = + | { + type: 'locations'; + locations: Array<{ + exists?: boolean; + target: string; + entities: EntityName[]; + }>; + } + | { + type: 'repository'; + url: string; + integrationType: string; + pullRequest: { + url: string; + }; + locations: Array<{ + target: string; + entities: EntityName[]; + }>; + }; -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "StepPrepareCreatePullRequest" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const StepPrepareCreatePullRequest: ({ - analyzeResult, - onPrepare, - onGoBack, - renderFormFields, -}: Props_9) => JSX.Element; +// @public +export const PreviewCatalogInfoComponent: ( + props: PreviewCatalogInfoComponentProps, +) => JSX.Element; + +// @public +export interface PreviewCatalogInfoComponentProps { + // (undocumented) + classes?: { + card?: string; + cardContent?: string; + }; + // (undocumented) + entities: Entity[]; + // (undocumented) + repositoryUrl: string; +} + +// @public +export const PreviewPullRequestComponent: ( + props: PreviewPullRequestComponentProps, +) => JSX.Element; + +// @public +export interface PreviewPullRequestComponentProps { + // (undocumented) + classes?: { + card?: string; + cardContent?: string; + }; + // (undocumented) + description: string; + // (undocumented) + title: string; +} + +// @public +export const StepInitAnalyzeUrl: ( + props: StepInitAnalyzeUrlProps, +) => JSX.Element; + +// @public +export interface StepInitAnalyzeUrlProps { + // (undocumented) + analysisUrl?: string; + // (undocumented) + disablePullRequest?: boolean; + // (undocumented) + exampleLocationUrl?: string; + // (undocumented) + onAnalysis: ( + flow: ImportFlows, + url: string, + result: AnalyzeResult, + opts?: { + prepareResult?: PrepareResult; + }, + ) => void; +} + +// @public +export const StepPrepareCreatePullRequest: ( + props: StepPrepareCreatePullRequestProps, +) => JSX.Element; + +// @public +export interface StepPrepareCreatePullRequestProps { + // (undocumented) + analyzeResult: Extract< + AnalyzeResult, + { + type: 'repository'; + } + >; + // (undocumented) + onGoBack?: () => void; + // (undocumented) + onPrepare: ( + result: PrepareResult, + opts?: { + notRepeatable?: boolean; + }, + ) => void; + // Warning: (ae-forgotten-export) The symbol "FormData" needs to be exported by the entry point index.d.ts + // + // (undocumented) + renderFormFields: ( + props: Pick< + UseFormReturn, + 'register' | 'setValue' | 'formState' + > & { + values: UnpackNestedValue; + groups: string[]; + groupsLoading: boolean; + }, + ) => React_2.ReactNode; +} // Warnings were encountered during analysis: // -// src/api/CatalogImportApi.d.ts:15:5 - (ae-forgotten-export) The symbol "PartialEntity" needs to be exported by the entry point index.d.ts +// src/api/CatalogImportApi.d.ts:25:5 - (ae-forgotten-export) The symbol "PartialEntity" needs to be exported by the entry point index.d.ts ``` diff --git a/plugins/catalog-import/src/api/CatalogImportApi.ts b/plugins/catalog-import/src/api/CatalogImportApi.ts index 5fae076479..0923f4ac98 100644 --- a/plugins/catalog-import/src/api/CatalogImportApi.ts +++ b/plugins/catalog-import/src/api/CatalogImportApi.ts @@ -18,11 +18,20 @@ import { EntityName } from '@backstage/catalog-model'; import { createApiRef } from '@backstage/core-plugin-api'; import { PartialEntity } from '../types'; +/** + * Utility API reference for the {@link CatalogImportApi}. + * + * @public + */ export const catalogImportApiRef = createApiRef({ id: 'plugin.catalog-import.service', }); -// result of the analyze state +/** + * Result of the analysis. + * + * @public + */ export type AnalyzeResult = | { type: 'locations'; @@ -39,6 +48,11 @@ export type AnalyzeResult = generatedEntities: PartialEntity[]; }; +/** + * API for driving catalog imports. + * + * @public + */ export interface CatalogImportApi { analyzeUrl(url: string): Promise; @@ -46,6 +60,7 @@ export interface CatalogImportApi { title: string; body: string; }>; + submitPullRequest(options: { repositoryUrl: string; fileContent: string; diff --git a/plugins/catalog-import/src/api/CatalogImportClient.ts b/plugins/catalog-import/src/api/CatalogImportClient.ts index 60745923b4..b856a4e359 100644 --- a/plugins/catalog-import/src/api/CatalogImportClient.ts +++ b/plugins/catalog-import/src/api/CatalogImportClient.ts @@ -34,6 +34,11 @@ import { getGithubIntegrationConfig } from './GitHub'; import { trimEnd } from 'lodash'; import { getBranchName, getCatalogFilename } from '../components/helpers'; +/** + * The default implementation of the {@link CatalogImportApi}. + * + * @public + */ export class CatalogImportClient implements CatalogImportApi { private readonly discoveryApi: DiscoveryApi; private readonly identityApi: IdentityApi; @@ -142,17 +147,14 @@ the component will become available.\n\nFor more information, read an \ }; } - async submitPullRequest({ - repositoryUrl, - fileContent, - title, - body, - }: { + async submitPullRequest(options: { repositoryUrl: string; fileContent: string; title: string; body: string; }): Promise<{ link: string; location: string }> { + const { repositoryUrl, fileContent, title, body } = options; + const ghConfig = getGithubIntegrationConfig( this.scmIntegrationsApi, repositoryUrl, @@ -172,9 +174,7 @@ the component will become available.\n\nFor more information, read an \ } // TODO: this could be part of the catalog api - private async generateEntityDefinitions({ - repo, - }: { + private async generateEntityDefinitions(options: { repo: string; }): Promise { const { token } = await this.identityApi.getCredentials(); @@ -187,7 +187,7 @@ the component will become available.\n\nFor more information, read an \ }, method: 'POST', body: JSON.stringify({ - location: { type: 'url', target: repo }, + location: { type: 'url', target: options.repo }, }), }, ).catch(e => { @@ -204,12 +204,7 @@ the component will become available.\n\nFor more information, read an \ } // TODO: this response should better be part of the analyze-locations response and scm-independent / implemented per scm - private async checkGitHubForExistingCatalogInfo({ - url, - owner, - repo, - githubIntegrationConfig, - }: { + private async checkGitHubForExistingCatalogInfo(options: { url: string; owner: string; repo: string; @@ -220,6 +215,8 @@ the component will become available.\n\nFor more information, read an \ entities: EntityName[]; }> > { + const { url, owner, repo, githubIntegrationConfig } = options; + const { token } = await this.scmAuthApi.getCredentials({ url }); const octo = new Octokit({ auth: token, @@ -269,15 +266,7 @@ the component will become available.\n\nFor more information, read an \ } // TODO: extract this function and implement for non-github - private async submitGitHubPrToRepo({ - owner, - repo, - title, - body, - fileContent, - repositoryUrl, - githubIntegrationConfig, - }: { + private async submitGitHubPrToRepo(options: { owner: string; repo: string; title: string; @@ -286,6 +275,16 @@ the component will become available.\n\nFor more information, read an \ repositoryUrl: string; githubIntegrationConfig: GitHubIntegrationConfig; }): Promise<{ link: string; location: string }> { + const { + owner, + repo, + title, + body, + fileContent, + repositoryUrl, + githubIntegrationConfig, + } = options; + const { token } = await this.scmAuthApi.getCredentials({ url: repositoryUrl, additionalScope: { diff --git a/plugins/catalog-import/src/components/DefaultImportPage/DefaultImportPage.tsx b/plugins/catalog-import/src/components/DefaultImportPage/DefaultImportPage.tsx index 8693895ec0..30cce9603a 100644 --- a/plugins/catalog-import/src/components/DefaultImportPage/DefaultImportPage.tsx +++ b/plugins/catalog-import/src/components/DefaultImportPage/DefaultImportPage.tsx @@ -27,6 +27,11 @@ import React from 'react'; import { ImportInfoCard } from '../ImportInfoCard'; import { ImportStepper } from '../ImportStepper'; +/** + * The default catalog import page. + * + * @public + */ export const DefaultImportPage = () => { const configApi = useApi(configApiRef); const appTitle = configApi.getOptional('app.title') || 'Backstage'; diff --git a/plugins/catalog-import/src/components/EntityListComponent/EntityListComponent.tsx b/plugins/catalog-import/src/components/EntityListComponent/EntityListComponent.tsx index b8af9942f6..2c59eec18f 100644 --- a/plugins/catalog-import/src/components/EntityListComponent/EntityListComponent.tsx +++ b/plugins/catalog-import/src/components/EntityListComponent/EntityListComponent.tsx @@ -47,23 +47,35 @@ function sortEntities(entities: Array) { ); } -type Props = { +/** + * Props for {@link EntityListComponent}. + * + * @public + */ +export interface EntityListComponentProps { locations: Array<{ target: string; entities: (Entity | EntityName)[] }>; locationListItemIcon: (target: string) => React.ReactElement; collapsed?: boolean; firstListItem?: React.ReactElement; onItemClick?: (target: string) => void; withLinks?: boolean; -}; +} + +/** + * Shows a result list of entities. + * + * @public + */ +export const EntityListComponent = (props: EntityListComponentProps) => { + const { + locations, + collapsed = false, + locationListItemIcon, + onItemClick, + firstListItem, + withLinks = false, + } = props; -export const EntityListComponent = ({ - locations, - collapsed = false, - locationListItemIcon, - onItemClick, - firstListItem, - withLinks = false, -}: Props) => { const app = useApp(); const classes = useStyles(); diff --git a/plugins/catalog-import/src/components/EntityListComponent/index.ts b/plugins/catalog-import/src/components/EntityListComponent/index.ts index 06b695240c..7fe0a0d55c 100644 --- a/plugins/catalog-import/src/components/EntityListComponent/index.ts +++ b/plugins/catalog-import/src/components/EntityListComponent/index.ts @@ -15,3 +15,4 @@ */ export { EntityListComponent } from './EntityListComponent'; +export type { EntityListComponentProps } from './EntityListComponent'; diff --git a/plugins/catalog-import/src/components/ImportInfoCard/ImportInfoCard.tsx b/plugins/catalog-import/src/components/ImportInfoCard/ImportInfoCard.tsx index 3e66e137eb..c879cbe998 100644 --- a/plugins/catalog-import/src/components/ImportInfoCard/ImportInfoCard.tsx +++ b/plugins/catalog-import/src/components/ImportInfoCard/ImportInfoCard.tsx @@ -21,15 +21,27 @@ import React from 'react'; import { catalogImportApiRef } from '../../api'; import { useCatalogFilename } from '../../hooks'; -type Props = { +/** + * Props for {@link ImportInfoCard}. + * + * @public + */ +export interface ImportInfoCardProps { exampleLocationUrl?: string; exampleRepositoryUrl?: string; -}; +} + +/** + * Shows information about the import process. + * + * @public + */ +export const ImportInfoCard = (props: ImportInfoCardProps) => { + const { + exampleLocationUrl = 'https://github.com/backstage/backstage/blob/master/catalog-info.yaml', + exampleRepositoryUrl = 'https://github.com/backstage/backstage', + } = props; -export const ImportInfoCard = ({ - exampleLocationUrl = 'https://github.com/backstage/backstage/blob/master/catalog-info.yaml', - exampleRepositoryUrl = 'https://github.com/backstage/backstage', -}: Props) => { const configApi = useApi(configApiRef); const appTitle = configApi.getOptional('app.title') || 'Backstage'; const catalogImportApi = useApi(catalogImportApiRef); diff --git a/plugins/catalog-import/src/components/ImportInfoCard/index.ts b/plugins/catalog-import/src/components/ImportInfoCard/index.ts index c82e88f7e8..10dc8726f6 100644 --- a/plugins/catalog-import/src/components/ImportInfoCard/index.ts +++ b/plugins/catalog-import/src/components/ImportInfoCard/index.ts @@ -15,3 +15,4 @@ */ export { ImportInfoCard } from './ImportInfoCard'; +export type { ImportInfoCardProps } from './ImportInfoCard'; diff --git a/plugins/catalog-import/src/components/ImportPage/ImportPage.tsx b/plugins/catalog-import/src/components/ImportPage/ImportPage.tsx index 467bd710f0..129e714952 100644 --- a/plugins/catalog-import/src/components/ImportPage/ImportPage.tsx +++ b/plugins/catalog-import/src/components/ImportPage/ImportPage.tsx @@ -18,6 +18,11 @@ import React from 'react'; import { useOutlet } from 'react-router'; import { DefaultImportPage } from '../DefaultImportPage'; +/** + * The whole catalog import page. + * + * @public + */ export const ImportPage = () => { const outlet = useOutlet(); diff --git a/plugins/catalog-import/src/components/ImportStepper/ImportStepper.tsx b/plugins/catalog-import/src/components/ImportStepper/ImportStepper.tsx index 4112775c2d..b2638e582e 100644 --- a/plugins/catalog-import/src/components/ImportStepper/ImportStepper.tsx +++ b/plugins/catalog-import/src/components/ImportStepper/ImportStepper.tsx @@ -34,20 +34,32 @@ const useStyles = makeStyles(() => ({ }, })); -type Props = { +/** + * Props for {@link ImportStepper}. + * + * @public + */ +export interface ImportStepperProps { initialUrl?: string; generateStepper?: ( flow: ImportFlows, defaults: StepperProvider, ) => StepperProvider; variant?: InfoCardVariants; -}; +} + +/** + * The stepper that holds the different import stages. + * + * @public + */ +export const ImportStepper = (props: ImportStepperProps) => { + const { + initialUrl, + generateStepper = defaultGenerateStepper, + variant, + } = props; -export const ImportStepper = ({ - initialUrl, - generateStepper = defaultGenerateStepper, - variant, -}: Props) => { const catalogImportApi = useApi(catalogImportApiRef); const classes = useStyles(); const state = useImportState({ initialUrl }); diff --git a/plugins/catalog-import/src/components/ImportStepper/defaults.tsx b/plugins/catalog-import/src/components/ImportStepper/defaults.tsx index 553e8977b8..94dff39d0f 100644 --- a/plugins/catalog-import/src/components/ImportStepper/defaults.tsx +++ b/plugins/catalog-import/src/components/ImportStepper/defaults.tsx @@ -42,7 +42,12 @@ export type StepConfiguration = { content: React.ReactElement; }; -export type StepperProvider = { +/** + * Defines the details of the stepper. + * + * @public + */ +export interface StepperProvider { analyze: ( s: Extract, opts: { apis: StepperApis }, @@ -59,7 +64,7 @@ export type StepperProvider = { s: Extract, opts: { apis: StepperApis }, ) => StepConfiguration; -}; +} /** * The default stepper generation function. @@ -69,6 +74,7 @@ export type StepperProvider = { * * @param flow - the name of the active flow * @param defaults - the default steps + * @public */ export function defaultGenerateStepper( flow: ImportFlows, diff --git a/plugins/catalog-import/src/components/ImportStepper/index.ts b/plugins/catalog-import/src/components/ImportStepper/index.ts index 164c6f43f1..db940f5f74 100644 --- a/plugins/catalog-import/src/components/ImportStepper/index.ts +++ b/plugins/catalog-import/src/components/ImportStepper/index.ts @@ -15,4 +15,5 @@ */ export { ImportStepper } from './ImportStepper'; +export type { ImportStepperProps } from './ImportStepper'; export { defaultGenerateStepper } from './defaults'; diff --git a/plugins/catalog-import/src/components/StepInitAnalyzeUrl/StepInitAnalyzeUrl.tsx b/plugins/catalog-import/src/components/StepInitAnalyzeUrl/StepInitAnalyzeUrl.tsx index 83377d6b2f..3c655ec11b 100644 --- a/plugins/catalog-import/src/components/StepInitAnalyzeUrl/StepInitAnalyzeUrl.tsx +++ b/plugins/catalog-import/src/components/StepInitAnalyzeUrl/StepInitAnalyzeUrl.tsx @@ -27,7 +27,12 @@ type FormData = { url: string; }; -type Props = { +/** + * Props for {@link StepInitAnalyzeUrl}. + * + * @public + */ +export interface StepInitAnalyzeUrlProps { onAnalysis: ( flow: ImportFlows, url: string, @@ -37,7 +42,7 @@ type Props = { disablePullRequest?: boolean; analysisUrl?: string; exampleLocationUrl?: string; -}; +} /** * A form that lets the user input a url and analyze it for existing locations or potential entities. @@ -45,13 +50,16 @@ type Props = { * @param onAnalysis - is called when the analysis was successful * @param analysisUrl - a url that can be used as a default value * @param disablePullRequest - if true, repositories without entities will abort the wizard + * @public */ -export const StepInitAnalyzeUrl = ({ - onAnalysis, - analysisUrl = '', - disablePullRequest = false, - exampleLocationUrl = 'https://github.com/backstage/backstage/blob/master/catalog-info.yaml', -}: Props) => { +export const StepInitAnalyzeUrl = (props: StepInitAnalyzeUrlProps) => { + const { + onAnalysis, + analysisUrl = '', + disablePullRequest = false, + exampleLocationUrl = 'https://github.com/backstage/backstage/blob/master/catalog-info.yaml', + } = props; + const errorApi = useApi(errorApiRef); const catalogImportApi = useApi(catalogImportApiRef); diff --git a/plugins/catalog-import/src/components/StepInitAnalyzeUrl/index.ts b/plugins/catalog-import/src/components/StepInitAnalyzeUrl/index.ts index 2cd1557d75..2a3dffcf99 100644 --- a/plugins/catalog-import/src/components/StepInitAnalyzeUrl/index.ts +++ b/plugins/catalog-import/src/components/StepInitAnalyzeUrl/index.ts @@ -15,3 +15,4 @@ */ export { StepInitAnalyzeUrl } from './StepInitAnalyzeUrl'; +export type { StepInitAnalyzeUrlProps } from './StepInitAnalyzeUrl'; diff --git a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/AutocompleteTextField.tsx b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/AutocompleteTextField.tsx index 98d741df15..2e163be2aa 100644 --- a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/AutocompleteTextField.tsx +++ b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/AutocompleteTextField.tsx @@ -20,7 +20,12 @@ import { Autocomplete } from '@material-ui/lab'; import React from 'react'; import { Controller, FieldErrors } from 'react-hook-form'; -type Props = { +/** + * Props for {@link AutocompleteTextField}. + * + * @public + */ +export interface AutocompleteTextFieldProps { name: TFieldValue; options: string[]; required?: boolean; @@ -35,20 +40,29 @@ type Props = { errorHelperText?: string; textFieldProps?: Omit; -}; +} + +/** + * An autocompletion text field for the catalog import flows. + * + * @public + */ +export const AutocompleteTextField = ( + props: AutocompleteTextFieldProps, +) => { + const { + name, + options, + required, + errors, + rules, + loading = false, + loadingText, + helperText, + errorHelperText, + textFieldProps = {}, + } = props; -export const AutocompleteTextField = ({ - name, - options, - required, - errors, - rules, - loading = false, - loadingText, - helperText, - errorHelperText, - textFieldProps = {}, -}: Props) => { return ( > = Pick< - UseFormProps, - 'defaultValues' -> & { +/** + * Props for {@link PreparePullRequestForm}. + * + * @public + */ +export type PreparePullRequestFormProps< + TFieldValues extends Record, +> = Pick, 'defaultValues'> & { onSubmit: SubmitHandler; render: ( @@ -48,14 +52,15 @@ type Props> = Pick< * @param onSubmit - a callback that is executed when the form is submitted * (initiated by a button of type="submit") * @param render - render the form elements + * @public */ export const PreparePullRequestForm = < TFieldValues extends Record, ->({ - defaultValues, - onSubmit, - render, -}: Props) => { +>( + props: PreparePullRequestFormProps, +) => { + const { defaultValues, onSubmit, render } = props; + const methods = useForm({ mode: 'onTouched', defaultValues }); const { handleSubmit, watch, control, register, formState, setValue } = methods; diff --git a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreviewCatalogInfoComponent.tsx b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreviewCatalogInfoComponent.tsx index 0f1dc33d2e..a16276f90b 100644 --- a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreviewCatalogInfoComponent.tsx +++ b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreviewCatalogInfoComponent.tsx @@ -22,17 +22,26 @@ import { CodeSnippet } from '@backstage/core-components'; import { trimEnd } from 'lodash'; import { useCatalogFilename } from '../../hooks'; -type Props = { +/** + * Props for {@link PreviewCatalogInfoComponent}. + * + * @public + */ +export interface PreviewCatalogInfoComponentProps { repositoryUrl: string; entities: Entity[]; classes?: { card?: string; cardContent?: string }; -}; +} -export const PreviewCatalogInfoComponent = ({ - repositoryUrl, - entities, - classes, -}: Props) => { +/** + * Previews information about an entity to create. + * + * @public + */ +export const PreviewCatalogInfoComponent = ( + props: PreviewCatalogInfoComponentProps, +) => { + const { repositoryUrl, entities, classes } = props; const catalogFilename = useCatalogFilename(); return ( diff --git a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreviewPullRequestComponent.tsx b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreviewPullRequestComponent.tsx index 7b6653e4ca..e8a54489a0 100644 --- a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreviewPullRequestComponent.tsx +++ b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreviewPullRequestComponent.tsx @@ -18,17 +18,26 @@ import { Card, CardContent, CardHeader } from '@material-ui/core'; import React from 'react'; import { MarkdownContent } from '@backstage/core-components'; -type Props = { +/** + * Props for {@link PreviewPullRequestComponent}. + * + * @public + */ +export interface PreviewPullRequestComponentProps { title: string; description: string; classes?: { card?: string; cardContent?: string }; -}; +} -export const PreviewPullRequestComponent = ({ - title, - description, - classes, -}: Props) => { +/** + * Previews a pull request. + * + * @public + */ +export const PreviewPullRequestComponent = ( + props: PreviewPullRequestComponentProps, +) => { + const { title, description, classes } = props; return ( diff --git a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/StepPrepareCreatePullRequest.tsx b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/StepPrepareCreatePullRequest.tsx index a79caaa0b9..36e8c33a5c 100644 --- a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/StepPrepareCreatePullRequest.tsx +++ b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/StepPrepareCreatePullRequest.tsx @@ -53,7 +53,12 @@ type FormData = { useCodeowners: boolean; }; -type Props = { +/** + * Props for {@link StepPrepareCreatePullRequest}. + * + * @public + */ +export interface StepPrepareCreatePullRequestProps { analyzeResult: Extract; onPrepare: ( result: PrepareResult, @@ -71,7 +76,7 @@ type Props = { groupsLoading: boolean; }, ) => React.ReactNode; -}; +} export function generateEntities( entities: PartialEntity[], @@ -93,12 +98,16 @@ export function generateEntities( })); } -export const StepPrepareCreatePullRequest = ({ - analyzeResult, - onPrepare, - onGoBack, - renderFormFields, -}: Props) => { +/** + * Prepares a pull request. + * + * @public + */ +export const StepPrepareCreatePullRequest = ( + props: StepPrepareCreatePullRequestProps, +) => { + const { analyzeResult, onPrepare, onGoBack, renderFormFields } = props; + const classes = useStyles(); const catalogApi = useApi(catalogApiRef); const catalogImportApi = useApi(catalogImportApiRef); diff --git a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/index.ts b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/index.ts index 1e8eaea1b9..ce1cd40e19 100644 --- a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/index.ts +++ b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/index.ts @@ -15,7 +15,12 @@ */ export { AutocompleteTextField } from './AutocompleteTextField'; +export type { AutocompleteTextFieldProps } from './AutocompleteTextField'; export { PreparePullRequestForm } from './PreparePullRequestForm'; +export type { PreparePullRequestFormProps } from './PreparePullRequestForm'; export { PreviewCatalogInfoComponent } from './PreviewCatalogInfoComponent'; +export type { PreviewCatalogInfoComponentProps } from './PreviewCatalogInfoComponent'; export { PreviewPullRequestComponent } from './PreviewPullRequestComponent'; +export type { PreviewPullRequestComponentProps } from './PreviewPullRequestComponent'; export { StepPrepareCreatePullRequest } from './StepPrepareCreatePullRequest'; +export type { StepPrepareCreatePullRequestProps } from './StepPrepareCreatePullRequest'; diff --git a/plugins/catalog-import/src/components/index.ts b/plugins/catalog-import/src/components/index.ts index 886c679d2d..15f57e7219 100644 --- a/plugins/catalog-import/src/components/index.ts +++ b/plugins/catalog-import/src/components/index.ts @@ -20,3 +20,4 @@ export * from './ImportInfoCard'; export * from './ImportStepper'; export * from './StepInitAnalyzeUrl'; export * from './StepPrepareCreatePullRequest'; +export type { ImportFlows, ImportState, PrepareResult } from './useImportState'; diff --git a/plugins/catalog-import/src/components/useImportState.ts b/plugins/catalog-import/src/components/useImportState.ts index a1505b26b5..0cb6b59917 100644 --- a/plugins/catalog-import/src/components/useImportState.ts +++ b/plugins/catalog-import/src/components/useImportState.ts @@ -18,7 +18,11 @@ import { Entity, EntityName } from '@backstage/catalog-model'; import { useReducer } from 'react'; import { AnalyzeResult } from '../api'; -// the configuration of the stepper +/** + * The configuration of the stepper. + * + * @public + */ export type ImportFlows = | 'unknown' | 'single-location' @@ -28,7 +32,11 @@ export type ImportFlows = // the available states of the stepper type ImportStateTypes = 'analyze' | 'prepare' | 'review' | 'finish'; -// result of the prepare state +/** + * Result of the prepare state. + * + * @public + */ export type PrepareResult = | { type: 'locations'; diff --git a/plugins/catalog-import/src/plugin.ts b/plugins/catalog-import/src/plugin.ts index 52c1929dce..d9dd226792 100644 --- a/plugins/catalog-import/src/plugin.ts +++ b/plugins/catalog-import/src/plugin.ts @@ -34,6 +34,12 @@ export const rootRouteRef = createRouteRef({ id: 'catalog-import', }); +/** + * A plugin that helps the user in importing projects and YAML files into the + * catalog. + * + * @public + */ export const catalogImportPlugin = createPlugin({ id: 'catalog-import', apis: [ @@ -70,6 +76,11 @@ export const catalogImportPlugin = createPlugin({ }, }); +/** + * The page for importing projects and YAML files into the catalog. + * + * @public + */ export const CatalogImportPage = catalogImportPlugin.provide( createRoutableExtension({ name: 'CatalogImportPage', diff --git a/plugins/catalog-react/api-report.md b/plugins/catalog-react/api-report.md index 8c3ba0daa3..2c064a504f 100644 --- a/plugins/catalog-react/api-report.md +++ b/plugins/catalog-react/api-report.md @@ -105,22 +105,14 @@ export type CatalogReactUserListPickerClassKey = // @public @deprecated (undocumented) export const catalogRouteRef: RouteRef; -// Warning: (ae-missing-release-tag) "createDomainColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function createDomainColumn(): TableColumn; -// Warning: (ae-missing-release-tag) "createEntityRefColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) -function createEntityRefColumn({ - defaultKind, -}: { +function createEntityRefColumn(options: { defaultKind?: string; }): TableColumn; -// Warning: (ae-missing-release-tag) "createEntityRelationColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function createEntityRelationColumn({ title, @@ -136,28 +128,18 @@ function createEntityRelationColumn({ }; }): TableColumn; -// Warning: (ae-missing-release-tag) "createMetadataDescriptionColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function createMetadataDescriptionColumn(): TableColumn; -// Warning: (ae-missing-release-tag) "createOwnerColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function createOwnerColumn(): TableColumn; -// Warning: (ae-missing-release-tag) "createSpecLifecycleColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function createSpecLifecycleColumn(): TableColumn; -// Warning: (ae-missing-release-tag) "createSpecTypeColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function createSpecTypeColumn(): TableColumn; -// Warning: (ae-missing-release-tag) "createSystemColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) function createSystemColumn(): TableColumn; @@ -215,14 +197,18 @@ export class EntityKindFilter implements EntityFilter { readonly value: string; } -// Warning: (ae-forgotten-export) The symbol "EntityKindFilterProps" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "EntityKindPicker" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) -export const EntityKindPicker: ({ - initialFilter, - hidden, -}: EntityKindFilterProps) => JSX.Element | null; +export const EntityKindPicker: ( + props: EntityKindPickerProps, +) => JSX.Element | null; + +// @public +export interface EntityKindPickerProps { + // (undocumented) + hidden: boolean; + // (undocumented) + 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) // @@ -237,8 +223,6 @@ export class EntityLifecycleFilter implements EntityFilter { readonly values: string[]; } -// Warning: (ae-missing-release-tag) "EntityLifecyclePicker" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const EntityLifecyclePicker: () => JSX.Element | null; @@ -270,8 +254,6 @@ export class EntityOwnerFilter implements EntityFilter { readonly values: string[]; } -// Warning: (ae-missing-release-tag) "EntityOwnerPicker" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const EntityOwnerPicker: () => JSX.Element | null; @@ -289,10 +271,7 @@ export interface EntityProviderProps { entity?: Entity; } -// Warning: (ae-forgotten-export) The symbol "EntityRefLinkProps" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "EntityRefLink" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const EntityRefLink: React_2.ForwardRefExoticComponent< Pick< EntityRefLinkProps, @@ -581,16 +560,27 @@ export const EntityRefLink: React_2.ForwardRefExoticComponent< React_2.RefAttributes >; -// Warning: (ae-forgotten-export) The symbol "EntityRefLinksProps" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "EntityRefLinks" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export type EntityRefLinkProps = { + entityRef: Entity | EntityName; + defaultKind?: string; + title?: string; + children?: React_2.ReactNode; +} & Omit; + +// @public export const EntityRefLinks: ({ entityRefs, defaultKind, ...linkProps }: EntityRefLinksProps) => JSX.Element; +// @public +export type EntityRefLinksProps = { + entityRefs: (Entity | EntityName)[]; + 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) @@ -618,8 +608,6 @@ export const entityRouteRef: RouteRef<{ namespace: string; }>; -// Warning: (ae-missing-release-tag) "EntitySearchBar" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const EntitySearchBar: () => JSX.Element; @@ -631,18 +619,12 @@ export type EntitySourceLocation = { integrationType?: string; }; -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "EntityTable" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // Warning: (ae-missing-release-tag) "EntityTable" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // -// @public (undocumented) -export function EntityTable({ - entities, - title, - emptyContent, - variant, - columns, -}: Props): JSX.Element; +// @public +export function EntityTable( + props: EntityTableProps, +): JSX.Element; // @public (undocumented) export namespace EntityTable { @@ -656,6 +638,22 @@ 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) + columns: TableColumn[]; + // (undocumented) + emptyContent?: ReactNode; + // (undocumented) + entities: T[]; + // (undocumented) + title: string; + // (undocumented) + 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) @@ -669,8 +667,6 @@ export class EntityTagFilter implements EntityFilter { readonly values: string[]; } -// Warning: (ae-missing-release-tag) "EntityTagPicker" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const EntityTagPicker: () => JSX.Element | null; @@ -700,26 +696,24 @@ export class EntityTypeFilter implements EntityFilter { readonly value: string | string[]; } -// Warning: (ae-missing-release-tag) "EntityTypeFilterProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export type EntityTypeFilterProps = { - initialFilter?: string; - hidden?: boolean; -}; - -// Warning: (ae-missing-release-tag) "EntityTypePicker" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export const EntityTypePicker: ( - props: EntityTypeFilterProps, + props: EntityTypePickerProps, ) => JSX.Element | null; +// @public +export interface EntityTypePickerProps { + // (undocumented) + hidden?: boolean; + // (undocumented) + 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_2) => JSX.Element; +export const FavoriteEntity: (props: Props) => 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) // @@ -835,7 +829,7 @@ export const UnregisterEntityDialog: ({ onConfirm, onClose, entity, -}: Props_3) => JSX.Element; +}: Props_2) => JSX.Element; // @public export function useEntity(): { diff --git a/plugins/catalog-react/src/components/EntityKindPicker/EntityKindPicker.tsx b/plugins/catalog-react/src/components/EntityKindPicker/EntityKindPicker.tsx index 6f9119c404..17d28aad9f 100644 --- a/plugins/catalog-react/src/components/EntityKindPicker/EntityKindPicker.tsx +++ b/plugins/catalog-react/src/components/EntityKindPicker/EntityKindPicker.tsx @@ -19,15 +19,20 @@ import { Alert } from '@material-ui/lab'; import { useEntityListProvider } from '../../hooks'; import { EntityKindFilter } from '../../filters'; -type EntityKindFilterProps = { +/** + * Props for {@link EntityKindPicker}. + * + * @public + */ +export interface EntityKindPickerProps { initialFilter?: string; hidden: boolean; -}; +} + +/** @public */ +export const EntityKindPicker = (props: EntityKindPickerProps) => { + const { initialFilter, hidden } = props; -export const EntityKindPicker = ({ - initialFilter, - hidden, -}: EntityKindFilterProps) => { const { updateFilters, queryParameters } = useEntityListProvider(); const [selectedKind] = useState( [queryParameters.kind].flat()[0] ?? initialFilter, diff --git a/plugins/catalog-react/src/components/EntityKindPicker/index.ts b/plugins/catalog-react/src/components/EntityKindPicker/index.ts index 89dd46230b..a89a96aebc 100644 --- a/plugins/catalog-react/src/components/EntityKindPicker/index.ts +++ b/plugins/catalog-react/src/components/EntityKindPicker/index.ts @@ -15,3 +15,4 @@ */ export { EntityKindPicker } from './EntityKindPicker'; +export type { EntityKindPickerProps } from './EntityKindPicker'; diff --git a/plugins/catalog-react/src/components/EntityLifecyclePicker/EntityLifecyclePicker.tsx b/plugins/catalog-react/src/components/EntityLifecyclePicker/EntityLifecyclePicker.tsx index 630b1700a0..f5f973b829 100644 --- a/plugins/catalog-react/src/components/EntityLifecyclePicker/EntityLifecyclePicker.tsx +++ b/plugins/catalog-react/src/components/EntityLifecyclePicker/EntityLifecyclePicker.tsx @@ -46,6 +46,7 @@ const useStyles = makeStyles( const icon = ; const checkedIcon = ; +/** @public */ export const EntityLifecyclePicker = () => { const classes = useStyles(); const { updateFilters, backendEntities, filters, queryParameters } = diff --git a/plugins/catalog-react/src/components/EntityOwnerPicker/EntityOwnerPicker.tsx b/plugins/catalog-react/src/components/EntityOwnerPicker/EntityOwnerPicker.tsx index ae88858666..e807155b0c 100644 --- a/plugins/catalog-react/src/components/EntityOwnerPicker/EntityOwnerPicker.tsx +++ b/plugins/catalog-react/src/components/EntityOwnerPicker/EntityOwnerPicker.tsx @@ -48,6 +48,7 @@ const useStyles = makeStyles( const icon = ; const checkedIcon = ; +/** @public */ export const EntityOwnerPicker = () => { const classes = useStyles(); const { updateFilters, backendEntities, filters, queryParameters } = diff --git a/plugins/catalog-react/src/components/EntityRefLink/EntityRefLink.tsx b/plugins/catalog-react/src/components/EntityRefLink/EntityRefLink.tsx index 02e63e60e3..aa92fd0818 100644 --- a/plugins/catalog-react/src/components/EntityRefLink/EntityRefLink.tsx +++ b/plugins/catalog-react/src/components/EntityRefLink/EntityRefLink.tsx @@ -13,6 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + import { Entity, EntityName, @@ -25,6 +26,11 @@ import { Link, LinkProps } from '@backstage/core-components'; import { useRouteRef } from '@backstage/core-plugin-api'; import { Tooltip } from '@material-ui/core'; +/** + * Props for {@link EntityRefLink}. + * + * @public + */ export type EntityRefLinkProps = { entityRef: Entity | EntityName; defaultKind?: string; @@ -32,6 +38,11 @@ export type EntityRefLinkProps = { children?: React.ReactNode; } & Omit; +/** + * Shows a clickable link to an entity. + * + * @public + */ export const EntityRefLink = forwardRef( (props, ref) => { const { entityRef, defaultKind, title, children, ...linkProps } = props; diff --git a/plugins/catalog-react/src/components/EntityRefLink/EntityRefLinks.tsx b/plugins/catalog-react/src/components/EntityRefLink/EntityRefLinks.tsx index 4a990f4028..9be970aa56 100644 --- a/plugins/catalog-react/src/components/EntityRefLink/EntityRefLinks.tsx +++ b/plugins/catalog-react/src/components/EntityRefLink/EntityRefLinks.tsx @@ -13,16 +13,27 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + import { Entity, EntityName } from '@backstage/catalog-model'; import React from 'react'; import { EntityRefLink } from './EntityRefLink'; import { LinkProps } from '@backstage/core-components'; +/** + * Props for {@link EntityRefLink}. + * + * @public + */ export type EntityRefLinksProps = { entityRefs: (Entity | EntityName)[]; defaultKind?: string; } & Omit; +/** + * Shows a list of clickable links to entities. + * + * @public + */ export const EntityRefLinks = ({ entityRefs, defaultKind, diff --git a/plugins/catalog-react/src/components/EntityRefLink/index.ts b/plugins/catalog-react/src/components/EntityRefLink/index.ts index 1c5297e2f2..d49993feb6 100644 --- a/plugins/catalog-react/src/components/EntityRefLink/index.ts +++ b/plugins/catalog-react/src/components/EntityRefLink/index.ts @@ -13,6 +13,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + export { EntityRefLink } from './EntityRefLink'; +export type { EntityRefLinkProps } from './EntityRefLink'; export { EntityRefLinks } from './EntityRefLinks'; +export type { EntityRefLinksProps } from './EntityRefLinks'; export { formatEntityRefTitle } from './format'; diff --git a/plugins/catalog-react/src/components/EntitySearchBar/EntitySearchBar.tsx b/plugins/catalog-react/src/components/EntitySearchBar/EntitySearchBar.tsx index 79b2ee36bf..ec977fada4 100644 --- a/plugins/catalog-react/src/components/EntitySearchBar/EntitySearchBar.tsx +++ b/plugins/catalog-react/src/components/EntitySearchBar/EntitySearchBar.tsx @@ -45,6 +45,7 @@ const useStyles = makeStyles( }, ); +/** @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 43da2b3612..62c33701b4 100644 --- a/plugins/catalog-react/src/components/EntityTable/EntityTable.tsx +++ b/plugins/catalog-react/src/components/EntityTable/EntityTable.tsx @@ -21,13 +21,18 @@ import * as columnFactories from './columns'; import { componentEntityColumns, systemEntityColumns } from './presets'; import { Table, TableColumn } from '@backstage/core-components'; -type Props = { +/** + * Props for {@link EntityTable}. + * + * @public + */ +export interface EntityTableProps { title: string; variant?: 'gridItem'; entities: T[]; emptyContent?: ReactNode; columns: TableColumn[]; -}; +} const useStyles = makeStyles(theme => ({ empty: { @@ -37,13 +42,21 @@ const useStyles = makeStyles(theme => ({ }, })); -export function EntityTable({ - entities, - title, - emptyContent, - variant = 'gridItem', - columns, -}: Props) { +/** + * A general entity table component, that can be used for composing more + * specific entity tables. + * + * @public + */ +export function EntityTable(props: EntityTableProps) { + const { + entities, + title, + emptyContent, + variant = 'gridItem', + columns, + } = props; + const classes = useStyles(); const tableStyle: React.CSSProperties = { minWidth: '0', diff --git a/plugins/catalog-react/src/components/EntityTable/columns.tsx b/plugins/catalog-react/src/components/EntityTable/columns.tsx index 1f4f5ee0d0..f6198fa1dc 100644 --- a/plugins/catalog-react/src/components/EntityTable/columns.tsx +++ b/plugins/catalog-react/src/components/EntityTable/columns.tsx @@ -29,11 +29,11 @@ import { formatEntityRefTitle, } from '../EntityRefLink'; -export function createEntityRefColumn({ - defaultKind, -}: { +/** @public */ +export function createEntityRefColumn(options: { defaultKind?: string; }): TableColumn { + const { defaultKind } = options; function formatContent(entity: T): string { return ( entity.metadata?.title || @@ -49,7 +49,7 @@ export function createEntityRefColumn({ customFilterAndSearch(filter, entity) { // TODO: We could implement this more efficiently, like searching over // each field that is displayed individually (kind, namespace, name). - // but that migth confuse the user as it will behave different than a + // but that might confuse the user as it will behave different than a // simple text search. // Another alternative would be to cache the values. But writing them // into the entity feels bad too. @@ -70,6 +70,7 @@ export function createEntityRefColumn({ }; } +/** @public */ export function createEntityRelationColumn({ title, relation, @@ -110,6 +111,7 @@ export function createEntityRelationColumn({ }; } +/** @public */ export function createOwnerColumn(): TableColumn { return createEntityRelationColumn({ title: 'Owner', @@ -118,6 +120,7 @@ export function createOwnerColumn(): TableColumn { }); } +/** @public */ export function createDomainColumn(): TableColumn { return createEntityRelationColumn({ title: 'Domain', @@ -129,6 +132,7 @@ export function createDomainColumn(): TableColumn { }); } +/** @public */ export function createSystemColumn(): TableColumn { return createEntityRelationColumn({ title: 'System', @@ -140,6 +144,7 @@ export function createSystemColumn(): TableColumn { }); } +/** @public */ export function createMetadataDescriptionColumn< T extends Entity, >(): TableColumn { @@ -157,6 +162,7 @@ export function createMetadataDescriptionColumn< }; } +/** @public */ export function createSpecLifecycleColumn(): TableColumn { return { title: 'Lifecycle', @@ -164,6 +170,7 @@ export function createSpecLifecycleColumn(): TableColumn { }; } +/** @public */ export function createSpecTypeColumn(): TableColumn { return { title: 'Type', diff --git a/plugins/catalog-react/src/components/EntityTable/index.ts b/plugins/catalog-react/src/components/EntityTable/index.ts index 36203e7929..2ed07f9823 100644 --- a/plugins/catalog-react/src/components/EntityTable/index.ts +++ b/plugins/catalog-react/src/components/EntityTable/index.ts @@ -13,4 +13,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + export { EntityTable } from './EntityTable'; +export type { EntityTableProps } from './EntityTable'; diff --git a/plugins/catalog-react/src/components/EntityTagPicker/EntityTagPicker.tsx b/plugins/catalog-react/src/components/EntityTagPicker/EntityTagPicker.tsx index a25c50c0a9..9f51a5df68 100644 --- a/plugins/catalog-react/src/components/EntityTagPicker/EntityTagPicker.tsx +++ b/plugins/catalog-react/src/components/EntityTagPicker/EntityTagPicker.tsx @@ -46,6 +46,7 @@ const useStyles = makeStyles( const icon = ; const checkedIcon = ; +/** @public */ export const EntityTagPicker = () => { const classes = useStyles(); const { updateFilters, backendEntities, filters, queryParameters } = diff --git a/plugins/catalog-react/src/components/EntityTypePicker/EntityTypePicker.tsx b/plugins/catalog-react/src/components/EntityTypePicker/EntityTypePicker.tsx index 225193dc93..a0770ef30a 100644 --- a/plugins/catalog-react/src/components/EntityTypePicker/EntityTypePicker.tsx +++ b/plugins/catalog-react/src/components/EntityTypePicker/EntityTypePicker.tsx @@ -22,12 +22,18 @@ import { useEntityTypeFilter } from '../../hooks/useEntityTypeFilter'; import { alertApiRef, useApi } from '@backstage/core-plugin-api'; import { Select } from '@backstage/core-components'; -export type EntityTypeFilterProps = { +/** + * Props for {@link EntityTypePicker}. + * + * @public + */ +export interface EntityTypePickerProps { initialFilter?: string; hidden?: boolean; -}; +} -export const EntityTypePicker = (props: EntityTypeFilterProps) => { +/** @public */ +export const EntityTypePicker = (props: EntityTypePickerProps) => { const { hidden, initialFilter } = props; const alertApi = useApi(alertApiRef); const { error, availableTypes, selectedTypes, setSelectedTypes } = diff --git a/plugins/catalog-react/src/components/EntityTypePicker/index.ts b/plugins/catalog-react/src/components/EntityTypePicker/index.ts index 1124b5c30c..03351337b7 100644 --- a/plugins/catalog-react/src/components/EntityTypePicker/index.ts +++ b/plugins/catalog-react/src/components/EntityTypePicker/index.ts @@ -15,4 +15,4 @@ */ export { EntityTypePicker } from './EntityTypePicker'; -export type { EntityTypeFilterProps } from './EntityTypePicker'; +export type { EntityTypePickerProps } from './EntityTypePicker'; diff --git a/plugins/catalog-react/src/components/index.ts b/plugins/catalog-react/src/components/index.ts index 0977e86d58..b80472a81d 100644 --- a/plugins/catalog-react/src/components/index.ts +++ b/plugins/catalog-react/src/components/index.ts @@ -13,6 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + export * from './EntityKindPicker'; export * from './EntityLifecyclePicker'; export * from './EntityOwnerPicker'; diff --git a/scripts/api-extractor.ts b/scripts/api-extractor.ts index dfbd91f76b..1ac43d242d 100644 --- a/scripts/api-extractor.ts +++ b/scripts/api-extractor.ts @@ -218,7 +218,9 @@ const NO_WARNING_PACKAGES = [ 'packages/types', 'packages/version-bridge', 'plugins/catalog-backend-module-ldap', + 'plugins/catalog-backend-module-msgraph', 'plugins/catalog-common', + 'plugins/catalog-graph', 'plugins/permission-backend', 'plugins/permission-common', 'plugins/permission-node',