diff --git a/plugins/scaffolder/api-report.md b/plugins/scaffolder/api-report.md index d4a2344499..90fee1fc66 100644 --- a/plugins/scaffolder/api-report.md +++ b/plugins/scaffolder/api-report.md @@ -43,25 +43,19 @@ export type CustomFieldValidator = ( }, ) => 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; }; -// 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; @@ -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; @@ -351,17 +302,13 @@ export interface ScaffolderScaffoldOptions { values: Record; } -// 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 diff --git a/plugins/scaffolder/src/components/Router.tsx b/plugins/scaffolder/src/components/Router.tsx index cedeaaca0f..3c906f21d4 100644 --- a/plugins/scaffolder/src/components/Router.tsx +++ b/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; diff --git a/plugins/scaffolder/src/components/TemplateTypePicker/TemplateTypePicker.tsx b/plugins/scaffolder/src/components/TemplateTypePicker/TemplateTypePicker.tsx index 0f18b34bb9..e7c2c965f2 100644 --- a/plugins/scaffolder/src/components/TemplateTypePicker/TemplateTypePicker.tsx +++ b/plugins/scaffolder/src/components/TemplateTypePicker/TemplateTypePicker.tsx @@ -34,6 +34,11 @@ import { alertApiRef, useApi } from '@backstage/core-plugin-api'; const icon = ; const checkedIcon = ; +/** + * 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 } = diff --git a/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.tsx b/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.tsx index 4a2f212fee..17c501d3a1 100644 --- a/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.tsx +++ b/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, diff --git a/plugins/scaffolder/src/components/fields/EntityTagsPicker/EntityTagsPicker.tsx b/plugins/scaffolder/src/components/fields/EntityTagsPicker/EntityTagsPicker.tsx index 41369a58eb..582fe57d72 100644 --- a/plugins/scaffolder/src/components/fields/EntityTagsPicker/EntityTagsPicker.tsx +++ b/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, diff --git a/plugins/scaffolder/src/components/fields/OwnedEntityPicker/OwnedEntityPicker.tsx b/plugins/scaffolder/src/components/fields/OwnedEntityPicker/OwnedEntityPicker.tsx index fb4a7a7234..5f314b6748 100644 --- a/plugins/scaffolder/src/components/fields/OwnedEntityPicker/OwnedEntityPicker.tsx +++ b/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, diff --git a/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.tsx b/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.tsx index 1824275380..5f9a05632c 100644 --- a/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.tsx +++ b/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, diff --git a/plugins/scaffolder/src/components/fields/RepoUrlPicker/RepoUrlPicker.tsx b/plugins/scaffolder/src/components/fields/RepoUrlPicker/RepoUrlPicker.tsx index 17fd5ef665..5af0295d55 100644 --- a/plugins/scaffolder/src/components/fields/RepoUrlPicker/RepoUrlPicker.tsx +++ b/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, diff --git a/plugins/scaffolder/src/components/fields/RepoUrlPicker/validation.ts b/plugins/scaffolder/src/components/fields/RepoUrlPicker/validation.ts index 24a1c2f5ce..ab5435f5d8 100644 --- a/plugins/scaffolder/src/components/fields/RepoUrlPicker/validation.ts +++ b/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, diff --git a/plugins/scaffolder/src/index.ts b/plugins/scaffolder/src/index.ts index 34b9155d66..bdca2a0952 100644 --- a/plugins/scaffolder/src/index.ts +++ b/plugins/scaffolder/src/index.ts @@ -22,7 +22,6 @@ export { scaffolderApiRef, ScaffolderClient } from './api'; export type { - JobStatus, ListActionsResponse, LogEvent, ScaffolderApi, diff --git a/plugins/scaffolder/src/plugin.ts b/plugins/scaffolder/src/plugin.ts index 0d44a40c80..eb8c0743a4 100644 --- a/plugins/scaffolder/src/plugin.ts +++ b/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, diff --git a/plugins/scaffolder/src/types.ts b/plugins/scaffolder/src/types.ts index 069c28d85c..8a67abeedb 100644 --- a/plugins/scaffolder/src/types.ts +++ b/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; secrets?: Record; } +/** + * 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;