chore: removed the last of the deprecations and fixed up the api-RepoUrlPickerFieldExtension

Signed-off-by: blam <ben@blam.sh>

plugins/scaffolder/api-report.md

@@ -43,25 +43,19 @@ export type CustomFieldValidator<TFieldReturnValue> = (
   },
 ) => void;
 
-// Warning: (ae-missing-release-tag) "EntityNamePickerFieldExtension" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const EntityNamePickerFieldExtension: FieldExtensionComponent<
   string,
   {}
 >;
 
-// Warning: (ae-missing-release-tag) "EntityPickerFieldExtension" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const EntityPickerFieldExtension: FieldExtensionComponent<
   string,
   EntityPickerUiOptions
 >;
 
-// Warning: (ae-missing-release-tag) "EntityPickerUiOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface EntityPickerUiOptions {
   // (undocumented)
   allowArbitraryValues?: boolean;
@@ -77,9 +71,7 @@ export const EntityTagsPickerFieldExtension: FieldExtensionComponent<
   EntityTagsPickerUiOptions
 >;
 
-// Warning: (ae-missing-release-tag) "EntityTagsPickerUiOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface EntityTagsPickerUiOptions {
   // (undocumented)
   kinds?: string[];
@@ -111,14 +103,7 @@ export type FieldExtensionOptions<
   validation?: CustomFieldValidator<TFieldReturnValue>;
 };
 
-// Warning: (ae-missing-release-tag) "JobStatus" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
-export type JobStatus = 'PENDING' | 'STARTED' | 'COMPLETED' | 'FAILED';
-
-// Warning: (ae-missing-release-tag) "ListActionsResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type ListActionsResponse = Array<{
   id: string;
   description?: string;
@@ -128,9 +113,7 @@ export type ListActionsResponse = Array<{
   };
 }>;
 
-// Warning: (ae-missing-release-tag) "LogEvent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type LogEvent = {
   type: 'log' | 'completion';
   body: {
@@ -143,17 +126,13 @@ export type LogEvent = {
   taskId: string;
 };
 
-// Warning: (ae-missing-release-tag) "OwnedEntityPickerFieldExtension" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const OwnedEntityPickerFieldExtension: FieldExtensionComponent<
   string,
   OwnedEntityPickerUiOptions
 >;
 
-// Warning: (ae-missing-release-tag) "OwnedEntityPickerUiOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface OwnedEntityPickerUiOptions {
   // (undocumented)
   allowedKinds?: string[];
@@ -161,25 +140,19 @@ export interface OwnedEntityPickerUiOptions {
   defaultKind?: string;
 }
 
-// Warning: (ae-missing-release-tag) "OwnerPickerFieldExtension" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const OwnerPickerFieldExtension: FieldExtensionComponent<
   string,
   OwnerPickerUiOptions
 >;
 
-// Warning: (ae-missing-release-tag) "OwnerPickerUiOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface OwnerPickerUiOptions {
   // (undocumented)
   allowedKinds?: string[];
 }
 
-// Warning: (ae-missing-release-tag) "repoPickerValidation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const repoPickerValidation: (
   value: string,
   validation: FieldValidation,
@@ -188,17 +161,13 @@ export const repoPickerValidation: (
   },
 ) => void;
 
-// Warning: (ae-missing-release-tag) "RepoUrlPickerFieldExtension" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const RepoUrlPickerFieldExtension: FieldExtensionComponent<
   string,
   RepoUrlPickerUiOptions
 >;
 
-// Warning: (ae-missing-release-tag) "RepoUrlPickerUiOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface RepoUrlPickerUiOptions {
   // (undocumented)
   allowedHosts?: string[];
@@ -216,16 +185,8 @@ export interface RepoUrlPickerUiOptions {
   };
 }
 
-// Warning: (ae-missing-release-tag) "RouterProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type RouterProps = {
-  TemplateCardComponent?:
-    | ComponentType<{
-        template: TemplateEntityV1beta3;
-      }>
-    | undefined;
-  TaskPageComponent?: ComponentType<{}>;
   components?: {
     TemplateCardComponent?:
       | ComponentType<{
@@ -294,17 +255,13 @@ export class ScaffolderClient implements ScaffolderApi {
 // @public
 export const ScaffolderFieldExtensions: React_2.ComponentType;
 
-// Warning: (ae-missing-release-tag) "ScaffolderGetIntegrationsListOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface ScaffolderGetIntegrationsListOptions {
   // (undocumented)
   allowedHosts: string[];
 }
 
-// Warning: (ae-missing-release-tag) "ScaffolderGetIntegrationsListResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface ScaffolderGetIntegrationsListResponse {
   // (undocumented)
   integrations: {
@@ -322,14 +279,10 @@ export type ScaffolderOutputLink = {
   entityRef?: string;
 };
 
-// Warning: (ae-missing-release-tag) "ScaffolderPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const ScaffolderPage: (props: RouterProps) => JSX.Element;
 
-// Warning: (ae-missing-release-tag) "scaffolderPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const scaffolderPlugin: BackstagePlugin<
   {
     root: RouteRef<undefined>;
@@ -339,9 +292,7 @@ export const scaffolderPlugin: BackstagePlugin<
   }
 >;
 
-// Warning: (ae-missing-release-tag) "ScaffolderScaffoldOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface ScaffolderScaffoldOptions {
   // (undocumented)
   secrets?: Record<string, string>;
@@ -351,17 +302,13 @@ export interface ScaffolderScaffoldOptions {
   values: Record<string, JsonValue>;
 }
 
-// Warning: (ae-missing-release-tag) "ScaffolderScaffoldResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface ScaffolderScaffoldResponse {
   // (undocumented)
   taskId: string;
 }
 
-// Warning: (ae-missing-release-tag) "ScaffolderStreamLogsOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export interface ScaffolderStreamLogsOptions {
   // (undocumented)
   after?: number;
@@ -369,9 +316,7 @@ export interface ScaffolderStreamLogsOptions {
   taskId: string;
 }
 
-// Warning: (ae-missing-release-tag) "ScaffolderTask" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type ScaffolderTask = {
   id: string;
   spec: TaskSpec;
@@ -387,9 +332,7 @@ export type ScaffolderTaskOutput = {
   [key: string]: unknown;
 };
 
-// Warning: (ae-missing-release-tag) "ScaffolderTaskStatus" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type ScaffolderTaskStatus =
   | 'open'
   | 'processing'
@@ -411,9 +354,7 @@ export type TaskPageProps = {
   loadingText?: string;
 };
 
-// Warning: (ae-missing-release-tag) "TemplateParameterSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type TemplateParameterSchema = {
   title: string;
   steps: Array<{
@@ -422,9 +363,7 @@ export type TemplateParameterSchema = {
   }>;
 };
 
-// Warning: (ae-missing-release-tag) "TemplateTypePicker" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const TemplateTypePicker: () => JSX.Element | null;
 
 // @public

plugins/scaffolder/src/components/Router.tsx

@@ -32,14 +32,11 @@ import {
 } from '../extensions';
 import { useElementFilter } from '@backstage/core-plugin-api';
 
+/**
+ * The props for the entrypoint `ScaffolderPage` component the plugin.
+ * @public
+ */
 export type RouterProps = {
-  /** @deprecated use components.TemplateCardComponent instead */
-  TemplateCardComponent?:
-    | ComponentType<{ template: TemplateEntityV1beta3 }>
-    | undefined;
-  /** @deprecated use component.TaskPageComponent instead */
-  TaskPageComponent?: ComponentType<{}>;
-
   components?: {
     TemplateCardComponent?:
       | ComponentType<{ template: TemplateEntityV1beta3 }>
@@ -53,6 +50,11 @@ export type RouterProps = {
   }>;
 };
 
+/**
+ * The main entirypoint `Router` for the `ScaffolderPlugin`.
+ *
+ * @public
+ */
 export const Router = (props: RouterProps) => {
   const { groups, components = {} } = props;
 

plugins/scaffolder/src/components/TemplateTypePicker/TemplateTypePicker.tsx

@@ -34,6 +34,11 @@ import { alertApiRef, useApi } from '@backstage/core-plugin-api';
 const icon = <CheckBoxOutlineBlankIcon fontSize="small" />;
 const checkedIcon = <CheckBoxIcon fontSize="small" />;
 
+/**
+ * The component to select the `type` of `Template` that you will see in the table.
+ *
+ * @public
+ */
 export const TemplateTypePicker = () => {
   const alertApi = useApi(alertApiRef);
   const { error, loading, availableTypes, selectedTypes, setSelectedTypes } =

plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.tsx

@@ -25,6 +25,12 @@ import React, { useCallback, useEffect } from 'react';
 import useAsync from 'react-use/lib/useAsync';
 import { FieldExtensionComponentProps } from '../../../extensions';
 
+/**
+ * The input props that can be specified under `ui:options` for the
+ * `EntityPicker` field extension.
+ *
+ * @public
+ */
 export interface EntityPickerUiOptions {
   allowedKinds?: string[];
   defaultKind?: string;
@@ -32,7 +38,10 @@ export interface EntityPickerUiOptions {
 }
 
 /**
- * Entity Picker
+ * The underling component that is rendered in the form for the `EntityPicker`
+ * field extension.
+ *
+ * @public
  */
 export const EntityPicker = (
   props: FieldExtensionComponentProps<string, EntityPickerUiOptions>,

plugins/scaffolder/src/components/fields/EntityTagsPicker/EntityTagsPicker.tsx

@@ -24,11 +24,21 @@ import { FormControl, TextField } from '@material-ui/core';
 import { Autocomplete } from '@material-ui/lab';
 import { FieldExtensionComponentProps } from '../../../extensions';
 
+/**
+ * The input props that can be specified under `ui:options` for the
+ * `EntityTagsPicker` field extension.
+ *
+ * @public
+ */
 export interface EntityTagsPickerUiOptions {
   kinds?: string[];
 }
+
 /**
- * EntityTagsPicker
+ * The underling component that is rendered in the form for the `EntityTagsPicker`
+ * field extension.
+ *
+ * @public
  */
 export const EntityTagsPicker = (
   props: FieldExtensionComponentProps<string[], EntityTagsPickerUiOptions>,

plugins/scaffolder/src/components/fields/OwnedEntityPicker/OwnedEntityPicker.tsx

@@ -28,13 +28,22 @@ import useAsync from 'react-use/lib/useAsync';
 
 import { FieldExtensionComponentProps } from '../../../extensions';
 
+/**
+ * The input props that can be specified under `ui:options` for the
+ * `OwnedEntityPicker` field extension.
+ *
+ * @public
+ */
 export interface OwnedEntityPickerUiOptions {
   allowedKinds?: string[];
   defaultKind?: string;
 }
 
 /**
- * Owned Entity Picker
+ * The underling component that is rendered in the form for the `OwnedEntityPicker`
+ * field extension.
+ *
+ * @public
  */
 export const OwnedEntityPicker = (
   props: FieldExtensionComponentProps<string, OwnedEntityPickerUiOptions>,

plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.tsx

@@ -17,12 +17,21 @@ import React from 'react';
 import { EntityPicker } from '../EntityPicker/EntityPicker';
 import { FieldExtensionComponentProps } from '../../../extensions';
 
+/**
+ * The input props that can be specified under `ui:options` for the
+ * `OwnerPicker` field extension.
+ *
+ * @public
+ */
 export interface OwnerPickerUiOptions {
   allowedKinds?: string[];
 }
 
 /**
- * Owner Picker
+ * The underling component that is rendered in the form for the `OwnerPicker`
+ * field extension.
+ *
+ * @public
  */
 export const OwnerPicker = (
   props: FieldExtensionComponentProps<string, OwnerPickerUiOptions>,

plugins/scaffolder/src/components/fields/RepoUrlPicker/RepoUrlPicker.tsx

@@ -30,6 +30,12 @@ import { RepoUrlPickerState } from './types';
 import useDebounce from 'react-use/lib/useDebounce';
 import { useTemplateSecrets } from '../../secrets';
 
+/**
+ * The input props that can be specified under `ui:options` for the
+ * `RepoUrlPicker` field extension.
+ *
+ * @public
+ */
 export interface RepoUrlPickerUiOptions {
   allowedHosts?: string[];
   allowedOwners?: string[];
@@ -45,7 +51,10 @@ export interface RepoUrlPickerUiOptions {
 }
 
 /**
- * Repo Url Picker
+ * The underling component that is rendered in the form for the `RepoUrlPicker`
+ * field extension.
+ *
+ * @public
  */
 export const RepoUrlPicker = (
   props: FieldExtensionComponentProps<string, RepoUrlPickerUiOptions>,

plugins/scaffolder/src/components/fields/RepoUrlPicker/validation.ts

@@ -18,6 +18,13 @@ import { FieldValidation } from '@rjsf/core';
 import { ApiHolder } from '@backstage/core-plugin-api';
 import { scmIntegrationsApiRef } from '@backstage/integration-react';
 
+/**
+ * The validation function for the `repoUrl` that is returned from the
+ * field extension. Ensures that you have all the required fields filled for
+ * the different providers that exist.
+ *
+ * @public
+ */
 export const repoPickerValidation = (
   value: string,
   validation: FieldValidation,

plugins/scaffolder/src/index.ts

@@ -22,7 +22,6 @@
 
 export { scaffolderApiRef, ScaffolderClient } from './api';
 export type {
-  JobStatus,
   ListActionsResponse,
   LogEvent,
   ScaffolderApi,

plugins/scaffolder/src/plugin.ts

@@ -34,6 +34,10 @@ import {
 import { OwnedEntityPicker } from './components/fields/OwnedEntityPicker/OwnedEntityPicker';
 import { EntityTagsPicker } from './components/fields/EntityTagsPicker/EntityTagsPicker';
 
+/**
+ * The main plugin export for the scaffolder.
+ * @public
+ */
 export const scaffolderPlugin = createPlugin({
   id: 'scaffolder',
   apis: [
@@ -60,6 +64,11 @@ export const scaffolderPlugin = createPlugin({
   },
 });
 
+/**
+ * A field extension for selecting an Entity that exists in the Catalog.
+ *
+ * @public
+ */
 export const EntityPickerFieldExtension = scaffolderPlugin.provide(
   createScaffolderFieldExtension({
     component: EntityPicker,
@@ -67,6 +76,11 @@ export const EntityPickerFieldExtension = scaffolderPlugin.provide(
   }),
 );
 
+/**
+ * The field extension for selecting a name for a new Entity in the Catalog.
+ *
+ * @public
+ */
 export const EntityNamePickerFieldExtension = scaffolderPlugin.provide(
   createScaffolderFieldExtension({
     component: EntityNamePicker,
@@ -75,6 +89,12 @@ export const EntityNamePickerFieldExtension = scaffolderPlugin.provide(
   }),
 );
 
+/**
+ * The field extension which provides the ability to select a RepositoryUrl.
+ * Currently this is an encoded URL that looks something like the following `github.com?repo=myRepoName&owner=backstage`.
+ *
+ * @public
+ */
 export const RepoUrlPickerFieldExtension = scaffolderPlugin.provide(
   createScaffolderFieldExtension({
     component: RepoUrlPicker,
@@ -83,6 +103,11 @@ export const RepoUrlPickerFieldExtension = scaffolderPlugin.provide(
   }),
 );
 
+/**
+ * A field extensions for picking users and groups out of the Catalog.
+ *
+ * @public
+ */
 export const OwnerPickerFieldExtension = scaffolderPlugin.provide(
   createScaffolderFieldExtension({
     component: OwnerPicker,
@@ -90,6 +115,11 @@ export const OwnerPickerFieldExtension = scaffolderPlugin.provide(
   }),
 );
 
+/**
+ * The Router and main entrypoint to the Scaffolder plugin.
+ *
+ * @public
+ */
 export const ScaffolderPage = scaffolderPlugin.provide(
   createRoutableExtension({
     name: 'ScaffolderPage',
@@ -98,6 +128,11 @@ export const ScaffolderPage = scaffolderPlugin.provide(
   }),
 );
 
+/**
+ * A field extension to show all the Entities that are owned by the current logged-in User for use in templates.
+ *
+ * @public
+ */
 export const OwnedEntityPickerFieldExtension = scaffolderPlugin.provide(
   createScaffolderFieldExtension({
     component: OwnedEntityPicker,

plugins/scaffolder/src/types.ts

@@ -17,6 +17,11 @@ import { TaskSpec } from '@backstage/plugin-scaffolder-common';
 import { JsonObject, JsonValue, Observable } from '@backstage/types';
 import { JSONSchema7 } from 'json-schema';
 
+/**
+ * The status of each task in a Scaffolder Job
+ *
+ * @public
+ */
 export type ScaffolderTaskStatus =
   | 'open'
   | 'processing'
@@ -24,8 +29,11 @@ export type ScaffolderTaskStatus =
   | 'completed'
   | 'skipped';
 
-export type JobStatus = 'PENDING' | 'STARTED' | 'COMPLETED' | 'FAILED';
-
+/**
+ * The shape of each task returned from the `scaffolder-backend`
+ *
+ * @public
+ */
 export type ScaffolderTask = {
   id: string;
   spec: TaskSpec;
@@ -34,6 +42,11 @@ export type ScaffolderTask = {
   createdAt: string;
 };
 
+/**
+ * The response shape for the `listActions` call to the `scaffolder-backend`
+ *
+ * @public
+ */
 export type ListActionsResponse = Array<{
   id: string;
   description?: string;
@@ -58,6 +71,12 @@ export type ScaffolderTaskOutput = {
   [key: string]: unknown;
 };
 
+/**
+ * The shape of each entry of parameters which gets rendered
+ * as a seperate step in the wizard input
+ *
+ * @public
+ */
 export type TemplateParameterSchema = {
   title: string;
   steps: Array<{
@@ -66,6 +85,11 @@ export type TemplateParameterSchema = {
   }>;
 };
 
+/**
+ * The shape of a `LogEvent` message from the `scaffolder-backend`
+ *
+ * @public
+ */
 export type LogEvent = {
   type: 'log' | 'completion';
   body: {
@@ -78,24 +102,49 @@ export type LogEvent = {
   taskId: string;
 };
 
+/**
+ * The input options to the `scaffold` method of the `ScaffolderClient`.
+ *
+ * @public
+ */
 export interface ScaffolderScaffoldOptions {
   templateRef: string;
   values: Record<string, JsonValue>;
   secrets?: Record<string, string>;
 }
 
+/**
+ * The response shape of the `scaffold` method of the `ScaffolderClient`.
+ *
+ * @public
+ */
 export interface ScaffolderScaffoldResponse {
   taskId: string;
 }
 
+/**
+ * The arguments for `getIntergationsList`.
+ *
+ * @public
+ */
 export interface ScaffolderGetIntegrationsListOptions {
   allowedHosts: string[];
 }
 
+/**
+ * The response shape for `getIntegrationsList`.
+ *
+ * @public
+ */
 export interface ScaffolderGetIntegrationsListResponse {
   integrations: { type: string; title: string; host: string }[];
 }
 
+/**
+ * The input options to the `streamLogs` method of the `ScaffolderClient`.
+ *
+ * @public
+ */
 export interface ScaffolderStreamLogsOptions {
   taskId: string;
   after?: number;