@backstage/plugin-catalog-import 0.7.10 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # @backstage/plugin-catalog-import
 
+## 0.8.1
+
+### Patch Changes
+
+- 7bb1bde7f6: Minor API cleanups
+- Updated dependencies
+  - @backstage/catalog-client@0.6.0
+  - @backstage/core-components@0.8.8
+  - @backstage/plugin-catalog-react@0.6.14
+  - @backstage/integration-react@0.1.21
+
+## 0.8.1-next.0
+
+### Patch Changes
+
+- 7bb1bde7f6: Minor API cleanups
+- Updated dependencies
+  - @backstage/core-components@0.8.8-next.0
+  - @backstage/plugin-catalog-react@0.6.14-next.0
+  - @backstage/integration-react@0.1.21-next.0
+
+## 0.8.0
+
+### Minor Changes
+
+- 2e8764b95f: Make filename, branch name and examples URLs used in catalog import customizable.
+
+  Catalog backend ingestion loop can be already configured to fetch targets with custom catalog filename (other than `catalog-info.yaml`). It's now possible to customize said filename and branch name used in pull requests created by catalog import flow too. This allows organizations to further customize Backstage experience and to better reflect their branding.
+
+  Filename (default: `catalog-info.yaml`) and branch name (default: `backstage-integration`) used in pull requests can be configured in `app-config.yaml` as follows:
+
+  ```yaml
+  // app-config.yaml
+
+  catalog:
+    import:
+      entityFilename: anvil.yaml
+      pullRequestBranchName: anvil-integration
+  ```
+
+  Following React components have also been updated to accept optional props for providing example entity and repository paths:
+
+  ```tsx
+  <StepInitAnalyzeUrl
+    ...
+    exampleLocationUrl="https://github.com/acme-corp/our-awesome-api/blob/main/anvil.yaml"
+  />
+  ```
+
+  ```tsx
+  <ImportInfoCard
+    exampleLocationUrl="https://github.com/acme-corp/our-awesome-api/blob/main/anvil.yaml"
+    exampleRepositoryUrl="https://github.com/acme-corp/our-awesome-api"
+  />
+  ```
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/core-components@0.8.7
+  - @backstage/plugin-catalog-react@0.6.13
+  - @backstage/integration-react@0.1.20
+
+## 0.8.0-next.0
+
+### Minor Changes
+
+- 2e8764b95f: Make filename, branch name and examples URLs used in catalog import customizable.
+
+  Catalog backend ingestion loop can be already configured to fetch targets with custom catalog filename (other than `catalog-info.yaml`). It's now possible to customize said filename and branch name used in pull requests created by catalog import flow too. This allows organizations to further customize Backstage experience and to better reflect their branding.
+
+  Filename (default: `catalog-info.yaml`) and branch name (default: `backstage-integration`) used in pull requests can be configured in `app-config.yaml` as follows:
+
+  ```yaml
+  // app-config.yaml
+
+  catalog:
+    import:
+      entityFilename: anvil.yaml
+      pullRequestBranchName: anvil-integration
+  ```
+
+  Following React components have also been updated to accept optional props for providing example entity and repository paths:
+
+  ```tsx
+  <StepInitAnalyzeUrl
+    ...
+    exampleLocationUrl="https://github.com/acme-corp/our-awesome-api/blob/main/anvil.yaml"
+  />
+  ```
+
+  ```tsx
+  <ImportInfoCard
+    exampleLocationUrl="https://github.com/acme-corp/our-awesome-api/blob/main/anvil.yaml"
+    exampleRepositoryUrl="https://github.com/acme-corp/our-awesome-api"
+  />
+  ```
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/core-components@0.8.7-next.0
+  - @backstage/integration-react@0.1.20-next.0
+  - @backstage/plugin-catalog-react@0.6.13-next.0
+
 ## 0.7.10
 
 ### Patch Changes

package/README.md

@@ -35,39 +35,73 @@ import { CatalogImportPage } from '@backstage/plugin-catalog-import';
 
 ## Customizations
 
-### Disable the creation of Pull Requests
+### Custom layout
+
+A custom layout can be passed to the import page, as it's already
+supported by the search page. If no custom layout is passed, the default layout
+is used.
+
+```typescript
+<Route path="/catalog-import" element={<CatalogImportPage />}>
+  <Page themeId="home">
+    <Header title="Register an existing component" />
+    <Content>
+      <ContentHeader title="Start tracking your components">
+        <SupportButton>
+          Start tracking your component in Backstage by adding it to the
+          software catalog.
+        </SupportButton>
+      </ContentHeader>
+
+      <Grid container spacing={2} direction="row-reverse">
+        <Grid item xs={12} md={4} lg={6} xl={8}>
+          Hello World
+        </Grid>
+
+        <Grid item xs={12} md={8} lg={6} xl={4}>
+          <ImportStepper />
+        </Grid>
+      </Grid>
+    </Content>
+  </Page>
+</Route>
+```
 
-The pull request feature can be disabled by options that are passed to the `CatalogImportPage`:
+Previously it was possible to disable and customize the automatic pull request
+feature by passing options to `<CatalogImportPage>` (`pullRequest.disable` and
+`pullRequest.preparePullRequest`). This functionality is moved to the
+`CatalogImportApi` which now provides an optional `preparePullRequest()`
+function. The function can either be overridden to generate a different content
+for the pull request, or removed to disable this feature.
 
-```tsx
-// packages/app/src/App.tsx
+### Entity filename and branch name
 
-<Route
-  path="/catalog-import"
-  element={<CatalogImportPage pullRequest={{ disable: true }} />}
-/>
+Entity filename (default: `catalog-info.yaml`) and branch name (default: `backstage-integration`) used in pull requests can be configured in `app-config.yaml` as follows:
+
+```yaml
+// app-config.yaml
+
+catalog:
+  import:
+    entityFilename: anvil.yaml
+    pullRequestBranchName: anvil-integration
 ```
 
-### Customize the title and body of the Pull Request
+### Entity examples
 
-The pull request form is filled with a default title and body.
-This can be configured by options that are passed to the `CatalogImportPage`:
+Following React components accept optional props for providing custom example entity and repository paths:
 
 ```tsx
-// packages/app/src/App.tsx
+<StepInitAnalyzeUrl
+  ...
+  exampleLocationUrl="https://github.com/acme-corp/our-awesome-api/blob/main/anvil.yaml"
+/>
+```
 
-<Route
-  path="/catalog-import"
-  element={
-    <CatalogImportPage
-      pullRequest={{
-        preparePullRequest: () => ({
-          title: 'My title',
-          body: 'My **markdown** body',
-        }),
-      }}
-    />
-  }
+```tsx
+<ImportInfoCard
+  exampleLocationUrl="https://github.com/acme-corp/our-awesome-api/blob/main/anvil.yaml"
+  exampleRepositoryUrl="https://github.com/acme-corp/our-awesome-api"
 />
 ```
 

package/config.d.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export interface Config {
+  /**
+   * Configuration options for the catalog plugin.
+   */
+  catalog?: {
+    /**
+     * List of import flow specific options and attributes
+     */
+    import?: {
+      /**
+       * Catalog entity descriptor filename, defaults to "catalog-info.yaml"
+       * @visibility frontend
+       */
+      entityFilename?: string;
+      /**
+       * A branch name used in pull request when registering existing component via UI
+       * Valid git refname required, see: https://git-scm.com/docs/git-check-ref-format
+       * Defaults to "backstage-integration"
+       * @visibility frontend
+       */
+      pullRequestBranchName?: string;
+    };
+  };
+}

package/dist/esm/{index-1d37898f.esm.js → index-577cd187.esm.js}

@@ -29,4 +29,4 @@ const ImportPage = () => {
 };
 
 export { ImportPage };
-//# sourceMappingURL=index-1d37898f.esm.js.map
+//# sourceMappingURL=index-577cd187.esm.js.map

package/dist/esm/{index-1d37898f.esm.js.map → index-577cd187.esm.js.map}

@@ -1 +1 @@
-{"version":3,"file":"index-1d37898f.esm.js","sources":["../../src/components/ImportPage/ImportPage.tsx"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport React from 'react';\nimport { useOutlet } from 'react-router';\nimport { DefaultImportPage } from '../DefaultImportPage';\n\nexport const ImportPage = () => {\n  const outlet = useOutlet();\n\n  return outlet || <DefaultImportPage />;\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;MAoBa,aAAa,MAAM;AAC9B,QAAM,SAAS;AAEf,SAAO,8CAAW,mBAAD;AAAA;;;;"}
+{"version":3,"file":"index-577cd187.esm.js","sources":["../../src/components/ImportPage/ImportPage.tsx"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport React from 'react';\nimport { useOutlet } from 'react-router';\nimport { DefaultImportPage } from '../DefaultImportPage';\n\n/**\n * The whole catalog import page.\n *\n * @public\n */\nexport const ImportPage = () => {\n  const outlet = useOutlet();\n\n  return outlet || <DefaultImportPage />;\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;MAyBa,aAAa,MAAM;AAC9B,QAAM,SAAS;AAEf,SAAO,8CAAW,mBAAD;AAAA;;;;"}

package/dist/index.d.ts

@@ -10,14 +10,35 @@ import { CatalogApi } from '@backstage/catalog-client';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import { ScmAuthApi } from '@backstage/integration-react';
 
+/**
+ * A plugin that helps the user in importing projects and YAML files into the
+ * catalog.
+ *
+ * @public
+ */
 declare const catalogImportPlugin: _backstage_core_plugin_api.BackstagePlugin<{
     importPage: _backstage_core_plugin_api.RouteRef<undefined>;
 }, {}>;
+/**
+ * The page for importing projects and YAML files into the catalog.
+ *
+ * @public
+ */
 declare const CatalogImportPage: () => JSX.Element;
 
+/**
+ * The default catalog import page.
+ *
+ * @public
+ */
 declare const DefaultImportPage: () => JSX.Element;
 
-declare type Props$7 = {
+/**
+ * Props for {@link EntityListComponent}.
+ *
+ * @public
+ */
+interface EntityListComponentProps {
     locations: Array<{
         target: string;
         entities: (Entity | EntityName)[];
@@ -27,17 +48,46 @@ declare type Props$7 = {
     firstListItem?: React.ReactElement;
     onItemClick?: (target: string) => void;
     withLinks?: boolean;
-};
-declare const EntityListComponent: ({ locations, collapsed, locationListItemIcon, onItemClick, firstListItem, withLinks, }: Props$7) => JSX.Element;
+}
+/**
+ * Shows a result list of entities.
+ *
+ * @public
+ */
+declare const EntityListComponent: (props: EntityListComponentProps) => JSX.Element;
 
-declare const ImportInfoCard: () => JSX.Element;
+/**
+ * Props for {@link ImportInfoCard}.
+ *
+ * @public
+ */
+interface ImportInfoCardProps {
+    exampleLocationUrl?: string;
+    exampleRepositoryUrl?: string;
+}
+/**
+ * Shows information about the import process.
+ *
+ * @public
+ */
+declare const ImportInfoCard: (props: ImportInfoCardProps) => JSX.Element;
 
 declare type RecursivePartial<T> = {
     [P in keyof T]?: T[P] extends (infer U)[] ? RecursivePartial<U>[] : T[P] extends object ? RecursivePartial<T[P]> : T[P];
 };
 declare type PartialEntity = RecursivePartial<Entity>;
 
+/**
+ * Utility API reference for the {@link CatalogImportApi}.
+ *
+ * @public
+ */
 declare const catalogImportApiRef: _backstage_core_plugin_api.ApiRef<CatalogImportApi>;
+/**
+ * Result of the analysis.
+ *
+ * @public
+ */
 declare type AnalyzeResult = {
     type: 'locations';
     locations: Array<{
@@ -51,6 +101,11 @@ declare type AnalyzeResult = {
     integrationType: string;
     generatedEntities: PartialEntity[];
 };
+/**
+ * API for driving catalog imports.
+ *
+ * @public
+ */
 interface CatalogImportApi {
     analyzeUrl(url: string): Promise<AnalyzeResult>;
     preparePullRequest?(): Promise<{
@@ -68,6 +123,11 @@ interface CatalogImportApi {
     }>;
 }
 
+/**
+ * The default implementation of the {@link CatalogImportApi}.
+ *
+ * @public
+ */
 declare class CatalogImportClient implements CatalogImportApi {
     private readonly discoveryApi;
     private readonly identityApi;
@@ -88,7 +148,7 @@ declare class CatalogImportClient implements CatalogImportApi {
         title: string;
         body: string;
     }>;
-    submitPullRequest({ repositoryUrl, fileContent, title, body, }: {
+    submitPullRequest(options: {
         repositoryUrl: string;
         fileContent: string;
         title: string;
@@ -102,7 +162,17 @@ declare class CatalogImportClient implements CatalogImportApi {
     private submitGitHubPrToRepo;
 }
 
+/**
+ * The configuration of the stepper.
+ *
+ * @public
+ */
 declare type ImportFlows = 'unknown' | 'single-location' | 'multiple-locations' | 'no-location';
+/**
+ * Result of the prepare state.
+ *
+ * @public
+ */
 declare type PrepareResult = {
     type: 'locations';
     locations: Array<{
@@ -185,7 +255,12 @@ declare type StepConfiguration = {
     stepLabel: React.ReactElement;
     content: React.ReactElement;
 };
-declare type StepperProvider = {
+/**
+ * Defines the details of the stepper.
+ *
+ * @public
+ */
+interface StepperProvider {
     analyze: (s: Extract<ImportState, {
         activeState: 'analyze';
     }>, opts: {
@@ -206,7 +281,7 @@ declare type StepperProvider = {
     }>, opts: {
         apis: StepperApis;
     }) => StepConfiguration;
-};
+}
 /**
  * The default stepper generation function.
  *
@@ -215,33 +290,56 @@ declare type StepperProvider = {
  *
  * @param flow - the name of the active flow
  * @param defaults - the default steps
+ * @public
  */
 declare function defaultGenerateStepper(flow: ImportFlows, defaults: StepperProvider): StepperProvider;
 
-declare type Props$6 = {
+/**
+ * Props for {@link ImportStepper}.
+ *
+ * @public
+ */
+interface ImportStepperProps {
     initialUrl?: string;
     generateStepper?: (flow: ImportFlows, defaults: StepperProvider) => StepperProvider;
     variant?: InfoCardVariants;
-};
-declare const ImportStepper: ({ initialUrl, generateStepper, variant, }: Props$6) => JSX.Element;
+}
+/**
+ * The stepper that holds the different import stages.
+ *
+ * @public
+ */
+declare const ImportStepper: (props: ImportStepperProps) => JSX.Element;
 
-declare type Props$5 = {
+/**
+ * Props for {@link StepInitAnalyzeUrl}.
+ *
+ * @public
+ */
+interface StepInitAnalyzeUrlProps {
     onAnalysis: (flow: ImportFlows, url: string, result: AnalyzeResult, opts?: {
         prepareResult?: PrepareResult;
     }) => void;
     disablePullRequest?: boolean;
     analysisUrl?: string;
-};
+    exampleLocationUrl?: string;
+}
 /**
  * A form that lets the user input a url and analyze it for existing locations or potential entities.
  *
  * @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
  */
-declare const StepInitAnalyzeUrl: ({ onAnalysis, analysisUrl, disablePullRequest, }: Props$5) => JSX.Element;
+declare const StepInitAnalyzeUrl: (props: StepInitAnalyzeUrlProps) => JSX.Element;
 
-declare type Props$4<TFieldValue extends string> = {
+/**
+ * Props for {@link AutocompleteTextField}.
+ *
+ * @public
+ */
+interface AutocompleteTextFieldProps<TFieldValue extends string> {
     name: TFieldValue;
     options: string[];
     required?: boolean;
@@ -252,10 +350,20 @@ declare type Props$4<TFieldValue extends string> = {
     helperText?: React.ReactNode;
     errorHelperText?: string;
     textFieldProps?: Omit<TextFieldProps, 'required' | 'fullWidth'>;
-};
-declare const AutocompleteTextField: <TFieldValue extends string>({ name, options, required, errors, rules, loading, loadingText, helperText, errorHelperText, textFieldProps, }: Props$4<TFieldValue>) => JSX.Element;
+}
+/**
+ * An autocompletion text field for the catalog import flows.
+ *
+ * @public
+ */
+declare const AutocompleteTextField: <TFieldValue extends string>(props: AutocompleteTextFieldProps<TFieldValue>) => JSX.Element;
 
-declare type Props$3<TFieldValues extends Record<string, any>> = Pick<UseFormProps<TFieldValues>, 'defaultValues'> & {
+/**
+ * Props for {@link PreparePullRequestForm}.
+ *
+ * @public
+ */
+declare type PreparePullRequestFormProps<TFieldValues extends Record<string, any>> = Pick<UseFormProps<TFieldValues>, 'defaultValues'> & {
     onSubmit: SubmitHandler<TFieldValues>;
     render: (props: Pick<UseFormReturn<TFieldValues>, 'formState' | 'register' | 'control' | 'setValue'> & {
         values: UnpackNestedValue<TFieldValues>;
@@ -269,28 +377,49 @@ declare type Props$3<TFieldValues extends Record<string, any>> = Pick<UseFormPro
  * @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
  */
-declare const PreparePullRequestForm: <TFieldValues extends Record<string, any>>({ defaultValues, onSubmit, render, }: Props$3<TFieldValues>) => JSX.Element;
+declare const PreparePullRequestForm: <TFieldValues extends Record<string, any>>(props: PreparePullRequestFormProps<TFieldValues>) => JSX.Element;
 
-declare type Props$2 = {
+/**
+ * Props for {@link PreviewCatalogInfoComponent}.
+ *
+ * @public
+ */
+interface PreviewCatalogInfoComponentProps {
     repositoryUrl: string;
     entities: Entity[];
     classes?: {
         card?: string;
         cardContent?: string;
     };
-};
-declare const PreviewCatalogInfoComponent: ({ repositoryUrl, entities, classes, }: Props$2) => JSX.Element;
+}
+/**
+ * Previews information about an entity to create.
+ *
+ * @public
+ */
+declare const PreviewCatalogInfoComponent: (props: PreviewCatalogInfoComponentProps) => JSX.Element;
 
-declare type Props$1 = {
+/**
+ * Props for {@link PreviewPullRequestComponent}.
+ *
+ * @public
+ */
+interface PreviewPullRequestComponentProps {
     title: string;
     description: string;
     classes?: {
         card?: string;
         cardContent?: string;
     };
-};
-declare const PreviewPullRequestComponent: ({ title, description, classes, }: Props$1) => JSX.Element;
+}
+/**
+ * Previews a pull request.
+ *
+ * @public
+ */
+declare const PreviewPullRequestComponent: (props: PreviewPullRequestComponentProps) => JSX.Element;
 
 declare type FormData = {
     title: string;
@@ -299,7 +428,12 @@ declare type FormData = {
     owner: string;
     useCodeowners: boolean;
 };
-declare type Props = {
+/**
+ * Props for {@link StepPrepareCreatePullRequest}.
+ *
+ * @public
+ */
+interface StepPrepareCreatePullRequestProps {
     analyzeResult: Extract<AnalyzeResult, {
         type: 'repository';
     }>;
@@ -312,7 +446,12 @@ declare type Props = {
         groups: string[];
         groupsLoading: boolean;
     }) => React.ReactNode;
-};
-declare const StepPrepareCreatePullRequest: ({ analyzeResult, onPrepare, onGoBack, renderFormFields, }: Props) => JSX.Element;
+}
+/**
+ * Prepares a pull request.
+ *
+ * @public
+ */
+declare const StepPrepareCreatePullRequest: (props: StepPrepareCreatePullRequestProps) => JSX.Element;
 
-export { AnalyzeResult, AutocompleteTextField, CatalogImportApi, CatalogImportClient, CatalogImportPage, DefaultImportPage, EntityListComponent, ImportInfoCard, ImportStepper, PreparePullRequestForm, PreviewCatalogInfoComponent, PreviewPullRequestComponent, StepInitAnalyzeUrl, StepPrepareCreatePullRequest, catalogImportApiRef, catalogImportPlugin, defaultGenerateStepper, catalogImportPlugin as plugin };
+export { AnalyzeResult, AutocompleteTextField, AutocompleteTextFieldProps, CatalogImportApi, CatalogImportClient, CatalogImportPage, DefaultImportPage, EntityListComponent, EntityListComponentProps, ImportFlows, ImportInfoCard, ImportInfoCardProps, ImportState, ImportStepper, ImportStepperProps, PreparePullRequestForm, PreparePullRequestFormProps, PrepareResult, PreviewCatalogInfoComponent, PreviewCatalogInfoComponentProps, PreviewPullRequestComponent, PreviewPullRequestComponentProps, StepInitAnalyzeUrl, StepInitAnalyzeUrlProps, StepPrepareCreatePullRequest, StepPrepareCreatePullRequestProps, catalogImportApiRef, catalogImportPlugin, defaultGenerateStepper, catalogImportPlugin as plugin };