@backstage/plugin-scaffolder-react 0.0.0-nightly-20230111022819

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# @backstage/plugin-scaffolder-react
+
+## 0.0.0-nightly-20230111022819
+
+### Major Changes
+
+- b4955ed7b9: Re-home some of the common types, components, hooks and `scaffolderApiRef` for the `@backstage/plugin-scaffolder` to this package for easy re-use across things that want to interact with the `scaffolder`.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/catalog-model@0.0.0-nightly-20230111022819
+  - @backstage/plugin-scaffolder-common@0.0.0-nightly-20230111022819
+  - @backstage/catalog-client@0.0.0-nightly-20230111022819
+  - @backstage/plugin-catalog-react@0.0.0-nightly-20230111022819
+  - @backstage/core-components@0.0.0-nightly-20230111022819
+  - @backstage/core-plugin-api@0.0.0-nightly-20230111022819
+  - @backstage/errors@1.1.4
+  - @backstage/theme@0.2.16
+  - @backstage/types@1.0.2
+  - @backstage/version-bridge@1.0.3
+
+## 1.0.0-next.0
+
+### Major Changes
+
+- b4955ed7b9: Re-home some of the common types, components, hooks and `scaffolderApiRef` for the `@backstage/plugin-scaffolder` to this package for easy re-use across things that want to interact with the `scaffolder`.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/core-plugin-api@1.3.0-next.1
+  - @backstage/catalog-client@1.3.0-next.2
+  - @backstage/plugin-catalog-react@1.2.4-next.2
+  - @backstage/catalog-model@1.1.5-next.1
+  - @backstage/core-components@0.12.3-next.2
+  - @backstage/errors@1.1.4
+  - @backstage/theme@0.2.16
+  - @backstage/types@1.0.2
+  - @backstage/version-bridge@1.0.3
+  - @backstage/plugin-scaffolder-common@1.2.4-next.1

package/README.md

@@ -0,0 +1,12 @@
+# Scaffolder React
+
+This is shared code of the frontend part of the default Scaffolder plugin.
+
+It will implement the core API for working with the Scaffolder, and
+supplies components that can be reused by third-party plugins.
+
+## Links
+
+- [Frontend part of the plugin](https://github.com/backstage/backstage/tree/master/plugins/scaffolder)
+- [Backend part of the plugin](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend)
+- [The Backstage homepage](https://backstage.io)

package/alpha/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@backstage/plugin-scaffolder-react",
+  "version": "0.0.0-nightly-20230111022819",
+  "main": "../dist/index.esm.js",
+  "types": "../dist/index.alpha.d.ts"
+}

package/dist/index.alpha.d.ts

@@ -0,0 +1,496 @@
+/// <reference types="react" />
+
+import { ApiHolder } from '@backstage/core-plugin-api';
+import { ApiRef } from '@backstage/core-plugin-api';
+import { Dispatch } from 'react';
+import { Extension } from '@backstage/core-plugin-api';
+import { FieldProps } from '@rjsf/core';
+import { FieldProps as FieldProps_2 } from '@rjsf/utils';
+import { FieldValidation } from '@rjsf/core';
+import { FieldValidation as FieldValidation_2 } from '@rjsf/utils';
+import type { FormProps as FormProps_2 } from '@rjsf/core-v5';
+import { IconComponent } from '@backstage/core-plugin-api';
+import { JsonObject } from '@backstage/types';
+import { JSONSchema7 } from 'json-schema';
+import { JsonValue } from '@backstage/types';
+import { Observable } from '@backstage/types';
+import { PropsWithChildren } from 'react';
+import { default as React_2 } from 'react';
+import { SetStateAction } from 'react';
+import { TaskSpec } from '@backstage/plugin-scaffolder-common';
+import { TaskStep } from '@backstage/plugin-scaffolder-common';
+import { TemplateEntityV1beta3 } from '@backstage/plugin-scaffolder-common';
+import { UIOptionsType } from '@rjsf/utils';
+import { UiSchema } from '@rjsf/utils';
+
+/**
+ * The response shape for a single action in the `listActions` call to the `scaffolder-backend`
+ *
+ * @public
+ */
+export declare type Action = {
+    id: string;
+    description?: string;
+    schema?: {
+        input?: JSONSchema7;
+        output?: JSONSchema7;
+    };
+    examples?: ActionExample[];
+};
+
+/**
+ * A single action example
+ *
+ * @public
+ */
+export declare type ActionExample = {
+    description: string;
+    example: string;
+};
+
+/**
+ * Creates a field validation object for use in react jsonschema form
+ * @alpha
+ */
+export declare const createFieldValidation: () => FieldValidation_2;
+
+/**
+ * Method for creating field extensions that can be used in the scaffolder
+ * frontend form.
+ * @alpha
+ */
+export declare function createNextScaffolderFieldExtension<TReturnValue = unknown, TInputProps extends UIOptionsType = {}>(options: NextFieldExtensionOptions<TReturnValue, TInputProps>): Extension<FieldExtensionComponent<TReturnValue, TInputProps>>;
+
+/**
+ * Method for creating field extensions that can be used in the scaffolder
+ * frontend form.
+ * @public
+ */
+export declare function createScaffolderFieldExtension<TReturnValue = unknown, TInputProps = unknown>(options: FieldExtensionOptions<TReturnValue, TInputProps>): Extension<FieldExtensionComponent<TReturnValue, TInputProps>>;
+
+/**
+ * Type for the Custom Field Extension schema.
+ *
+ * @public
+ */
+export declare type CustomFieldExtensionSchema = {
+    returnValue: JSONSchema7;
+    uiOptions?: JSONSchema7;
+};
+
+/**
+ * Field validation type for Custom Field Extensions.
+ *
+ * @public
+ */
+export declare type CustomFieldValidator<TFieldReturnValue> = (data: TFieldReturnValue, field: FieldValidation, context: {
+    apiHolder: ApiHolder;
+}) => void | Promise<void>;
+
+/**
+ * Takes a step from a Backstage Template Manifest and converts it to a JSON Schema and UI Schema for rjsf
+ * @alpha
+ */
+export declare const extractSchemaFromStep: (inputStep: JsonObject) => {
+    uiSchema: UiSchema;
+    schema: JsonObject;
+};
+
+/**
+ * A type used to wrap up the FieldExtension to embed the ReturnValue and the InputProps
+ * @public
+ */
+export declare type FieldExtensionComponent<_TReturnValue, _TInputProps> = () => null;
+
+/**
+ * Type for field extensions and being able to type
+ * incoming props easier.
+ *
+ * @public
+ */
+export declare interface FieldExtensionComponentProps<TFieldReturnValue, TUiOptions extends {} = {}> extends FieldProps<TFieldReturnValue> {
+    uiSchema: FieldProps['uiSchema'] & {
+        'ui:options'?: TUiOptions;
+    };
+}
+
+/**
+ * Type for the Custom Field Extension with the
+ * name and components and validation function.
+ *
+ * @public
+ */
+export declare type FieldExtensionOptions<TFieldReturnValue = unknown, TInputProps = unknown> = {
+    name: string;
+    component: (props: FieldExtensionComponentProps<TFieldReturnValue, TInputProps>) => JSX.Element | null;
+    validation?: CustomFieldValidator<TFieldReturnValue>;
+    schema?: CustomFieldExtensionSchema;
+};
+
+/**
+ * Any `@rjsf/core` form properties that are publicly exposed to the `NextScaffolderpage`
+ *
+ * @alpha
+ */
+export declare type FormProps = Pick<FormProps_2, 'transformErrors' | 'noHtml5Validate'>;
+
+/**
+ * The response shape for the `listActions` call to the `scaffolder-backend`
+ *
+ * @public
+ */
+export declare type ListActionsResponse = Array<Action>;
+
+/**
+ * The shape of a `LogEvent` message from the `scaffolder-backend`
+ *
+ * @public
+ */
+export declare type LogEvent = {
+    type: 'log' | 'completion';
+    body: {
+        message: string;
+        stepId?: string;
+        status?: ScaffolderTaskStatus;
+    };
+    createdAt: string;
+    id: string;
+    taskId: string;
+};
+
+/**
+ * Field validation type for Custom Field Extensions.
+ *
+ * @alpha
+ */
+export declare type NextCustomFieldValidator<TFieldReturnValue> = (data: TFieldReturnValue, field: FieldValidation_2, context: {
+    apiHolder: ApiHolder;
+    formData: JsonObject;
+}) => void | Promise<void>;
+
+/**
+ * Type for Field Extension Props for RJSF v5
+ *
+ * @alpha
+ */
+export declare interface NextFieldExtensionComponentProps<TFieldReturnValue, TUiOptions = {}> extends PropsWithChildren<FieldProps_2<TFieldReturnValue>> {
+    uiSchema?: UiSchema<TFieldReturnValue> & {
+        'ui:options'?: TUiOptions & UIOptionsType;
+    };
+}
+
+/**
+ * Type for the Custom Field Extension with the
+ * name and components and validation function.
+ *
+ * @alpha
+ */
+export declare type NextFieldExtensionOptions<TFieldReturnValue = unknown, TInputProps = unknown> = {
+    name: string;
+    component: (props: NextFieldExtensionComponentProps<TFieldReturnValue, TInputProps>) => JSX.Element | null;
+    validation?: NextCustomFieldValidator<TFieldReturnValue>;
+    schema?: CustomFieldExtensionSchema;
+};
+
+/**
+ * This is the parsed template schema that is returned from the {@link useTemplateSchema} hook.
+ * @alpha
+ */
+export declare interface ParsedTemplateSchema {
+    uiSchema: UiSchema;
+    mergedSchema: JsonObject;
+    schema: JsonObject;
+    title: string;
+    description?: string;
+}
+
+/**
+ * The component used by the {@link Stepper} to render the review step.
+ * @alpha
+ */
+export declare const ReviewState: (props: ReviewStateProps) => JSX.Element;
+
+/**
+ * The props for the {@link ReviewState} component.
+ * @alpha
+ */
+export declare type ReviewStateProps = {
+    schemas: ParsedTemplateSchema[];
+    formState: JsonObject;
+};
+
+/**
+ * An API to interact with the scaffolder backend.
+ *
+ * @public
+ */
+export declare interface ScaffolderApi {
+    getTemplateParameterSchema(templateRef: string): Promise<TemplateParameterSchema>;
+    /**
+     * Executes the scaffolding of a component, given a template and its
+     * parameter values.
+     *
+     * @param options - The {@link ScaffolderScaffoldOptions} the scaffolding.
+     */
+    scaffold(options: ScaffolderScaffoldOptions): Promise<ScaffolderScaffoldResponse>;
+    getTask(taskId: string): Promise<ScaffolderTask>;
+    listTasks?(options: {
+        filterByOwnership: 'owned' | 'all';
+    }): Promise<{
+        tasks: ScaffolderTask[];
+    }>;
+    getIntegrationsList(options: ScaffolderGetIntegrationsListOptions): Promise<ScaffolderGetIntegrationsListResponse>;
+    /**
+     * Returns a list of all installed actions.
+     */
+    listActions(): Promise<ListActionsResponse>;
+    streamLogs(options: ScaffolderStreamLogsOptions): Observable<LogEvent>;
+    dryRun?(options: ScaffolderDryRunOptions): Promise<ScaffolderDryRunResponse>;
+}
+
+/** @public */
+export declare const scaffolderApiRef: ApiRef<ScaffolderApi>;
+
+/** @public */
+export declare interface ScaffolderDryRunOptions {
+    template: JsonValue;
+    values: JsonObject;
+    secrets?: Record<string, string>;
+    directoryContents: {
+        path: string;
+        base64Content: string;
+    }[];
+}
+
+/** @public */
+export declare interface ScaffolderDryRunResponse {
+    directoryContents: Array<{
+        path: string;
+        base64Content: string;
+        executable: boolean;
+    }>;
+    log: Array<Pick<LogEvent, 'body'>>;
+    steps: TaskStep[];
+    output: ScaffolderTaskOutput;
+}
+
+/**
+ * The Wrapping component for defining fields extensions inside
+ *
+ * @public
+ */
+export declare const ScaffolderFieldExtensions: React_2.ComponentType<React_2.PropsWithChildren<{}>>;
+
+/**
+ * The arguments for `getIntegrationsList`.
+ *
+ * @public
+ */
+export declare interface ScaffolderGetIntegrationsListOptions {
+    allowedHosts: string[];
+}
+
+/**
+ * The response shape for `getIntegrationsList`.
+ *
+ * @public
+ */
+export declare interface ScaffolderGetIntegrationsListResponse {
+    integrations: {
+        type: string;
+        title: string;
+        host: string;
+    }[];
+}
+
+/** @public */
+export declare type ScaffolderOutputLink = {
+    title?: string;
+    icon?: string;
+    url?: string;
+    entityRef?: string;
+};
+
+/**
+ * The input options to the `scaffold` method of the `ScaffolderClient`.
+ *
+ * @public
+ */
+export declare interface ScaffolderScaffoldOptions {
+    templateRef: string;
+    values: Record<string, JsonValue>;
+    secrets?: Record<string, string>;
+}
+
+/**
+ * The response shape of the `scaffold` method of the `ScaffolderClient`.
+ *
+ * @public
+ */
+export declare interface ScaffolderScaffoldResponse {
+    taskId: string;
+}
+
+/**
+ * The input options to the `streamLogs` method of the `ScaffolderClient`.
+ *
+ * @public
+ */
+export declare interface ScaffolderStreamLogsOptions {
+    taskId: string;
+    after?: number;
+}
+
+/**
+ * The shape of each task returned from the `scaffolder-backend`
+ *
+ * @public
+ */
+export declare type ScaffolderTask = {
+    id: string;
+    spec: TaskSpec;
+    status: 'failed' | 'completed' | 'processing' | 'open' | 'cancelled';
+    lastHeartbeatAt: string;
+    createdAt: string;
+};
+
+/** @public */
+export declare type ScaffolderTaskOutput = {
+    links?: ScaffolderOutputLink[];
+} & {
+    [key: string]: unknown;
+};
+
+/**
+ * The status of each task in a Scaffolder Job
+ *
+ * @public
+ */
+export declare type ScaffolderTaskStatus = 'open' | 'processing' | 'failed' | 'completed' | 'skipped';
+
+/**
+ * The return type from the useTemplateSecrets hook.
+ * @public
+ */
+export declare interface ScaffolderUseTemplateSecrets {
+    setSecrets: (input: Record<string, string>) => void;
+    secrets: Record<string, string>;
+}
+
+/**
+ * The Context Provider that holds the state for the secrets.
+ * @public
+ */
+export declare const SecretsContextProvider: ({ children }: PropsWithChildren<{}>) => JSX.Element;
+
+/**
+ * The `Stepper` component is the Wizard that is rendered when a user selects a template
+ * @alpha
+ */
+export declare const Stepper: (props: StepperProps) => JSX.Element;
+
+/**
+ * The Props for {@link Stepper} component
+ * @alpha
+ */
+export declare type StepperProps = {
+    manifest: TemplateParameterSchema;
+    extensions: NextFieldExtensionOptions<any, any>[];
+    templateName?: string;
+    FormProps?: FormProps;
+    initialState?: Record<string, JsonValue>;
+    onComplete: (values: Record<string, JsonValue>) => Promise<void>;
+};
+
+/**
+ * The `TemplateCard` component that is rendered in a list for each template
+ * @alpha
+ */
+export declare const TemplateCard: (props: TemplateCardProps) => JSX.Element;
+
+/**
+ * The Props for the {@link TemplateCard} component
+ * @alpha
+ */
+export declare interface TemplateCardProps {
+    template: TemplateEntityV1beta3;
+    additionalLinks?: {
+        icon: IconComponent;
+        text: string;
+        url: string;
+    }[];
+    onSelected?: (template: TemplateEntityV1beta3) => void;
+}
+
+/**
+ * The `TemplateGroup` component is used to display a group of templates with a title.
+ * @alpha
+ */
+export declare const TemplateGroup: (props: TemplateGroupProps) => JSX.Element;
+
+/**
+ * The props for the {@link TemplateGroup} component.
+ * @alpha
+ */
+export declare interface TemplateGroupProps {
+    templates: {
+        template: TemplateEntityV1beta3;
+        additionalLinks?: {
+            icon: IconComponent;
+            text: string;
+            url: string;
+        }[];
+    }[];
+    onSelected: (template: TemplateEntityV1beta3) => void;
+    title: React_2.ReactNode;
+    components?: {
+        CardComponent?: React_2.ComponentType<TemplateCardProps>;
+    };
+}
+
+/**
+ * The shape of each entry of parameters which gets rendered
+ * as a separate step in the wizard input
+ *
+ * @public
+ */
+export declare type TemplateParameterSchema = {
+    title: string;
+    description?: string;
+    steps: Array<{
+        title: string;
+        description?: string;
+        schema: JsonObject;
+    }>;
+};
+
+/**
+ * Hook that returns all custom field extensions from the current outlet.
+ * @public
+ */
+export declare const useCustomFieldExtensions: <TComponentDataType = FieldExtensionOptions<unknown, unknown>>(outlet: React.ReactNode) => TComponentDataType[];
+
+/**
+ * This hook is used to get the formData from the query string.
+ * @alpha
+ */
+export declare const useFormDataFromQuery: (initialState?: Record<string, JsonValue>) => [Record<string, any>, Dispatch<SetStateAction<Record<string, any>>>];
+
+/**
+ * This hook will parse the template schema and return the steps with the
+ * parsed schema and uiSchema. Filtering out any steps or properties that
+ * are not enabled with feature flags.
+ * @alpha
+ */
+export declare const useTemplateSchema: (manifest: TemplateParameterSchema) => {
+    steps: ParsedTemplateSchema[];
+};
+
+/**
+ * Hook to access the secrets context to be able to set secrets that are
+ * passed to the Scaffolder backend.
+ * @public
+ */
+export declare const useTemplateSecrets: () => ScaffolderUseTemplateSecrets;
+
+export { }