@backstage/frontend-plugin-api 0.3.0 → 0.4.0-next.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @backstage/frontend-plugin-api
 
+## 0.4.0-next.1
+
+### Minor Changes
+
+- a5a04739e1: The extension `factory` function now longer receives `id` or `source`, but instead now provides the extension's `AppNode` as `node`. The `ExtensionBoundary` component has also been updated to receive a `node` prop rather than `id` and `source`.
+
+### Patch Changes
+
+- 5eb6b8a7bc: Added the nav logo extension for customization of sidebar logo
+- 1f12fb762c: Create factories for overriding default core components extensions.
+- 59709286b3: Add feature flags to plugins and extension overrides.
+- e539735435: Added `createSignInPageExtension`.
+- f27ee7d937: Migrate analytics api and context files.
+- Updated dependencies
+  - @backstage/core-components@0.13.9-next.1
+  - @backstage/core-plugin-api@1.8.1-next.1
+  - @backstage/config@1.1.1
+  - @backstage/types@1.1.1
+  - @backstage/version-bridge@1.0.7
+
+## 0.3.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/core-plugin-api@1.8.1-next.0
+  - @backstage/core-components@0.13.9-next.0
+  - @backstage/config@1.1.1
+  - @backstage/types@1.1.1
+  - @backstage/version-bridge@1.0.7
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,10 +1,54 @@
 /// <reference types="react" />
+import React, { ReactNode, ComponentType, PropsWithChildren, JSX as JSX$1 } from 'react';
 import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
-import { IconComponent, AnyApiFactory, AppTheme, AnyApiRef } from '@backstage/core-plugin-api';
+import { BackstagePlugin as BackstagePlugin$1, IconComponent as IconComponent$1, AnyApiFactory, AppTheme, ApiRef, AnyApiRef, SignInPageProps } from '@backstage/core-plugin-api';
+export { AlertApi, AlertMessage, AnyApiFactory, AnyApiRef, ApiFactory, ApiHolder, ApiRef, ApiRefConfig, AppTheme, AppThemeApi, AuthProviderInfo, AuthRequestOptions, BackstageIdentityApi, BackstageIdentityResponse, BackstageUserIdentity, ConfigApi, DiscoveryApi, ErrorApi, ErrorApiError, ErrorApiErrorContext, FeatureFlag, FeatureFlagState, FeatureFlagsApi, FeatureFlagsSaveOptions, FetchApi, IdentityApi, OAuthApi, OAuthRequestApi, OAuthRequester, OAuthRequesterOptions, OAuthScope, OpenIdConnectApi, PendingOAuthRequest, ProfileInfo, ProfileInfoApi, SessionApi, SessionState, StorageApi, StorageValueSnapshot, TypesToApiRefs, alertApiRef, appThemeApiRef, atlassianAuthApiRef, bitbucketAuthApiRef, bitbucketServerAuthApiRef, configApiRef, createApiFactory, createApiRef, discoveryApiRef, errorApiRef, featureFlagsApiRef, fetchApiRef, githubAuthApiRef, gitlabAuthApiRef, googleAuthApiRef, identityApiRef, microsoftAuthApiRef, oauthRequestApiRef, oktaAuthApiRef, oneloginAuthApiRef, storageApiRef, useApi, useApiHolder, withApis } from '@backstage/core-plugin-api';
 import { JsonObject } from '@backstage/types';
-import React, { JSX as JSX$1, ReactNode } from 'react';
 import { z, ZodSchema, ZodTypeDef } from 'zod';
 
+/**
+ * Common analytics context attributes.
+ *
+ * @public
+ */
+type CommonAnalyticsContext = {
+    /**
+     * The nearest known parent plugin where the event was captured.
+     */
+    pluginId: string;
+    /**
+     * The nearest known parent extension where the event was captured.
+     */
+    /**
+     * The nearest known parent extension where the event was captured.
+     */
+    extensionId: string;
+};
+/**
+ * Analytics context envelope.
+ *
+ * @public
+ */
+type AnalyticsContextValue = CommonAnalyticsContext & {
+    [param in string]: string | boolean | number | undefined;
+};
+
+/**
+ * Provides components in the child react tree an Analytics Context, ensuring
+ * all analytics events captured within the context have relevant attributes.
+ *
+ * @remarks
+ *
+ * Analytics contexts are additive, meaning the context ultimately emitted with
+ * an event is the combination of all contexts in the parent tree.
+ *
+ * @public
+ */
+declare const AnalyticsContext: (options: {
+    attributes: Partial<AnalyticsContextValue>;
+    children: ReactNode;
+}) => React.JSX.Element;
+
 /**
  * Catch-all type for route params.
  *
@@ -216,13 +260,63 @@ interface ConfigurableExtensionDataRef<TData, TConfig extends {
 /** @public */
 declare function createExtensionDataRef<TData>(id: string): ConfigurableExtensionDataRef<TData>;
 
+/**
+ * Utility type to expand type aliases into their equivalent type.
+ * @ignore
+ */
+type Expand<T> = T extends infer O ? {
+    [K in keyof O]: O[K];
+} : never;
+/** @public */
+type CoreProgressComponent = ComponentType<PropsWithChildren<{}>>;
+/** @public */
+type CoreBootErrorPageComponent = ComponentType<PropsWithChildren<{
+    step: 'load-config' | 'load-chunk';
+    error: Error;
+}>>;
+/** @public */
+type CoreNotFoundErrorPageComponent = ComponentType<PropsWithChildren<{}>>;
+/** @public */
+type CoreErrorBoundaryFallbackComponent = ComponentType<PropsWithChildren<{
+    plugin?: BackstagePlugin$1;
+    error: Error;
+    resetError: () => void;
+}>>;
+
+/** @public */
+type ComponentRef<T> = {
+    id: string;
+    T: T;
+};
+/** @public */
+declare const coreComponentsRefs: {
+    progress: ComponentRef<CoreProgressComponent>;
+    bootErrorPage: ComponentRef<CoreBootErrorPageComponent>;
+    notFoundErrorPage: ComponentRef<CoreNotFoundErrorPageComponent>;
+    errorBoundaryFallback: ComponentRef<CoreErrorBoundaryFallbackComponent>;
+};
+
+/** @public */
+interface ExtensionBoundaryProps {
+    node: AppNode;
+    routable?: boolean;
+    children: ReactNode;
+}
+/** @public */
+declare function ExtensionBoundary(props: ExtensionBoundaryProps): React.JSX.Element;
+
 /** @public */
 type NavTarget = {
     title: string;
-    icon: IconComponent;
+    icon: IconComponent$1;
     routeRef: RouteRef<undefined>;
 };
 /** @public */
+type LogoElements = {
+    logoIcon?: JSX$1.Element;
+    logoFull?: JSX$1.Element;
+};
+/** @public */
 declare const coreExtensionData: {
     reactElement: ConfigurableExtensionDataRef<JSX$1.Element, {}>;
     routePath: ConfigurableExtensionDataRef<string, {}>;
@@ -230,6 +324,11 @@ declare const coreExtensionData: {
     routeRef: ConfigurableExtensionDataRef<RouteRef<AnyRouteRefParams>, {}>;
     navTarget: ConfigurableExtensionDataRef<NavTarget, {}>;
     theme: ConfigurableExtensionDataRef<AppTheme, {}>;
+    logoElements: ConfigurableExtensionDataRef<LogoElements, {}>;
+    component: ConfigurableExtensionDataRef<{
+        ref: ComponentRef<ComponentType<any>>;
+        impl: ComponentType<any>;
+    }, {}>;
 };
 
 /** @public */
@@ -241,14 +340,6 @@ type PortableSchema<TOutput> = {
 /** @public */
 declare function createSchemaFromZod<TOutput, TInput>(schemaCreator: (zImpl: typeof z) => ZodSchema<TOutput, ZodTypeDef, TInput>): PortableSchema<TOutput>;
 
-/**
- * Utility type to expand type aliases into their equivalent type.
- * @ignore
- */
-type Expand<T> = T extends infer O ? {
-    [K in keyof O]: O[K];
-} : never;
-
 /** @public */
 interface ExtensionInput<TExtensionData extends AnyExtensionDataMap, TConfig extends {
     singleton: boolean;
@@ -267,32 +358,6 @@ declare function createExtensionInput<TExtensionData extends AnyExtensionDataMap
     optional: TConfig['optional'] extends true ? true : false;
 }>;
 
-/** @public */
-type AnyRoutes = {
-    [name in string]: RouteRef;
-};
-/** @public */
-type AnyExternalRoutes = {
-    [name in string]: ExternalRouteRef;
-};
-/** @public */
-interface PluginOptions<Routes extends AnyRoutes, ExternalRoutes extends AnyExternalRoutes> {
-    id: string;
-    routes?: Routes;
-    externalRoutes?: ExternalRoutes;
-    extensions?: Extension<unknown>[];
-}
-/** @public */
-interface BackstagePlugin<Routes extends AnyRoutes = AnyRoutes, ExternalRoutes extends AnyExternalRoutes = AnyExternalRoutes> {
-    $$type: '@backstage/BackstagePlugin';
-    id: string;
-    extensions: Extension<unknown>[];
-    routes: Routes;
-    externalRoutes: ExternalRoutes;
-}
-/** @public */
-declare function createPlugin<Routes extends AnyRoutes = {}, ExternalRoutes extends AnyExternalRoutes = {}>(options: PluginOptions<Routes, ExternalRoutes>): BackstagePlugin<Routes, ExternalRoutes>;
-
 /** @public */
 type AnyExtensionDataMap = {
     [name in string]: ExtensionDataRef<unknown, {
@@ -340,7 +405,7 @@ interface CreateExtensionOptions<TOutput extends AnyExtensionDataMap, TInputs ex
     output: TOutput;
     configSchema?: PortableSchema<TConfig>;
     factory(options: {
-        source?: BackstagePlugin;
+        node: AppNode;
         config: TConfig;
         inputs: Expand<ExtensionInputValues<TInputs>>;
     }): Expand<ExtensionDataValues<TOutput>>;
@@ -358,7 +423,7 @@ interface Extension<TConfig> {
     output: AnyExtensionDataMap;
     configSchema?: PortableSchema<TConfig>;
     factory(options: {
-        source?: BackstagePlugin;
+        node: AppNode;
         config: TConfig;
         inputs: Record<string, undefined | Record<string, unknown> | Array<Record<string, unknown>>>;
     }): ExtensionDataValues<any>;
@@ -366,13 +431,50 @@ interface Extension<TConfig> {
 /** @public */
 declare function createExtension<TOutput extends AnyExtensionDataMap, TInputs extends AnyExtensionInputMap, TConfig = never>(options: CreateExtensionOptions<TOutput, TInputs, TConfig>): Extension<TConfig>;
 
+/**
+ * Feature flag configuration.
+ *
+ * @public
+ */
+type FeatureFlagConfig = {
+    /** Feature flag name */
+    name: string;
+};
+
+/** @public */
+type AnyRoutes = {
+    [name in string]: RouteRef;
+};
+/** @public */
+type AnyExternalRoutes = {
+    [name in string]: ExternalRouteRef;
+};
+/** @public */
+interface PluginOptions<Routes extends AnyRoutes, ExternalRoutes extends AnyExternalRoutes> {
+    id: string;
+    routes?: Routes;
+    externalRoutes?: ExternalRoutes;
+    extensions?: Extension<unknown>[];
+    featureFlags?: FeatureFlagConfig[];
+}
+/** @public */
+interface BackstagePlugin<Routes extends AnyRoutes = AnyRoutes, ExternalRoutes extends AnyExternalRoutes = AnyExternalRoutes> {
+    readonly $$type: '@backstage/BackstagePlugin';
+    readonly id: string;
+    readonly routes: Routes;
+    readonly externalRoutes: ExternalRoutes;
+}
+/** @public */
+declare function createPlugin<Routes extends AnyRoutes = {}, ExternalRoutes extends AnyExternalRoutes = {}>(options: PluginOptions<Routes, ExternalRoutes>): BackstagePlugin<Routes, ExternalRoutes>;
+
 /** @public */
 interface ExtensionOverridesOptions {
     extensions: Extension<unknown>[];
+    featureFlags?: FeatureFlagConfig[];
 }
 /** @public */
 interface ExtensionOverrides {
-    $$type: '@backstage/ExtensionOverrides';
+    readonly $$type: '@backstage/ExtensionOverrides';
 }
 /** @public */
 declare function createExtensionOverrides(options: ExtensionOverridesOptions): ExtensionOverrides;
@@ -475,15 +577,126 @@ interface AppTreeApi {
  */
 declare const appTreeApiRef: _backstage_core_plugin_api.ApiRef<AppTreeApi>;
 
-/** @public */
-interface ExtensionBoundaryProps {
-    id: string;
-    source?: BackstagePlugin;
-    routable?: boolean;
-    children: ReactNode;
+/**
+ * API for looking up components based on component refs.
+ *
+ * @public
+ */
+interface ComponentsApi {
+    getComponent<T>(ref: ComponentRef<T>): T;
 }
-/** @public */
-declare function ExtensionBoundary(props: ExtensionBoundaryProps): React.JSX.Element;
+/**
+ * The `ApiRef` of {@link ComponentsApi}.
+ *
+ * @public
+ */
+declare const componentsApiRef: _backstage_core_plugin_api.ApiRef<ComponentsApi>;
+
+/**
+ * Represents an event worth tracking in an analytics system that could inform
+ * how users of a Backstage instance are using its features.
+ *
+ * @public
+ */
+type AnalyticsEvent = {
+    /**
+     * A string that identifies the event being tracked by the type of action the
+     * event represents. Be careful not to encode extra metadata in this string
+     * that should instead be placed in the Analytics Context or attributes.
+     * Examples include:
+     *
+     * - view
+     * - click
+     * - filter
+     * - search
+     * - hover
+     * - scroll
+     */
+    action: string;
+    /**
+     * A string that uniquely identifies the object that the action is being
+     * taken on. Examples include:
+     *
+     * - The path of the page viewed
+     * - The url of the link clicked
+     * - The value that was filtered by
+     * - The text that was searched for
+     */
+    subject: string;
+    /**
+     * An optional numeric value relevant to the event that could be aggregated
+     * by analytics tools. Examples include:
+     *
+     * - The index or position of the clicked element in an ordered list
+     * - The percentage of an element that has been scrolled through
+     * - The amount of time that has elapsed since a fixed point
+     * - A satisfaction score on a fixed scale
+     */
+    value?: number;
+    /**
+     * Optional, additional attributes (representing dimensions or metrics)
+     * specific to the event that could be forwarded on to analytics systems.
+     */
+    attributes?: AnalyticsEventAttributes;
+    /**
+     * Contextual metadata relating to where the event was captured and by whom.
+     * This could include information about the route, plugin, or extension in
+     * which an event was captured.
+     */
+    context: AnalyticsContextValue;
+};
+/**
+ * A structure allowing other arbitrary metadata to be provided by analytics
+ * event emitters.
+ *
+ * @public
+ */
+type AnalyticsEventAttributes = {
+    [attribute in string]: string | boolean | number;
+};
+/**
+ * Represents a tracker with methods that can be called to track events in a
+ * configured analytics service.
+ *
+ * @public
+ */
+type AnalyticsTracker = {
+    captureEvent: (action: string, subject: string, options?: {
+        value?: number;
+        attributes?: AnalyticsEventAttributes;
+    }) => void;
+};
+/**
+ * The Analytics API is used to track user behavior in a Backstage instance.
+ *
+ * @remarks
+ *
+ * To instrument your App or Plugin, retrieve an analytics tracker using the
+ * useAnalytics() hook. This will return a pre-configured AnalyticsTracker
+ * with relevant methods for instrumentation.
+ *
+ * @public
+ */
+type AnalyticsApi = {
+    /**
+     * Primary event handler responsible for compiling and forwarding events to
+     * an analytics system.
+     */
+    captureEvent(event: AnalyticsEvent): void;
+};
+/**
+ * The API reference of {@link AnalyticsApi}.
+ *
+ * @public
+ */
+declare const analyticsApiRef: ApiRef<AnalyticsApi>;
+
+/**
+ * Gets a pre-configured analytics tracker.
+ *
+ * @public
+ */
+declare function useAnalytics(): AnalyticsTracker;
 
 /** @public */
 declare function createApiExtension<TConfig extends {}, TInputs extends AnyExtensionInputMap>(options: ({
@@ -533,12 +746,72 @@ declare function createNavItemExtension(options: {
     id: string;
     routeRef: RouteRef<undefined>;
     title: string;
-    icon: IconComponent;
+    icon: IconComponent$1;
 }): Extension<{
     title: string;
 }>;
 
+/**
+ *
+ * @public
+ */
+declare function createSignInPageExtension<TConfig extends {}, TInputs extends AnyExtensionInputMap>(options: {
+    id: string;
+    attachTo?: {
+        id: string;
+        input: string;
+    };
+    configSchema?: PortableSchema<TConfig>;
+    disabled?: boolean;
+    inputs?: TInputs;
+    loader: (options: {
+        config: TConfig;
+        inputs: Expand<ExtensionInputValues<TInputs>>;
+    }) => Promise<ComponentType<SignInPageProps>>;
+}): Extension<TConfig>;
+
 /** @public */
 declare function createThemeExtension(theme: AppTheme): Extension<never>;
 
-export { AnyExtensionDataMap, AnyExtensionInputMap, AnyExternalRoutes, AnyRouteRefParams, AnyRoutes, AppNode, AppNodeEdges, AppNodeInstance, AppNodeSpec, AppTree, AppTreeApi, BackstagePlugin, ConfigurableExtensionDataRef, CreateExtensionOptions, Extension, ExtensionBoundary, ExtensionBoundaryProps, ExtensionDataRef, ExtensionDataValues, ExtensionInput, ExtensionInputValues, ExtensionOverrides, ExtensionOverridesOptions, ExternalRouteRef, NavTarget, PluginOptions, PortableSchema, RouteFunc, RouteRef, SubRouteRef, appTreeApiRef, coreExtensionData, createApiExtension, createExtension, createExtensionDataRef, createExtensionInput, createExtensionOverrides, createExternalRouteRef, createNavItemExtension, createPageExtension, createPlugin, createRouteRef, createSchemaFromZod, createSubRouteRef, createThemeExtension, useRouteRef, useRouteRefParams };
+/** @public */
+declare function createComponentExtension<TRef extends ComponentRef<any>, TConfig extends {}, TInputs extends AnyExtensionInputMap>(options: {
+    ref: TRef;
+    disabled?: boolean;
+    inputs?: TInputs;
+    configSchema?: PortableSchema<TConfig>;
+    component: {
+        lazy: (values: {
+            config: TConfig;
+            inputs: Expand<ExtensionInputValues<TInputs>>;
+        }) => Promise<TRef['T']>;
+    } | {
+        sync: (values: {
+            config: TConfig;
+            inputs: Expand<ExtensionInputValues<TInputs>>;
+        }) => TRef['T'];
+    };
+}): Extension<TConfig>;
+
+/**
+ * IconComponent is the common icon type used throughout Backstage when
+ * working with and rendering generic icons, including the app system icons.
+ *
+ * @remarks
+ *
+ * The type is based on SvgIcon from Material UI, but both do not what the plugin-api
+ * package to have a dependency on Material UI, nor do we want the props to be as broad
+ * as the SvgIconProps interface.
+ *
+ * If you have the need to forward additional props from SvgIconProps, you can
+ * open an issue or submit a PR to the main Backstage repo. When doing so please
+ * also describe your use-case and reasoning of the addition.
+ *
+ * @public
+ */
+type IconComponent = ComponentType<{
+    fontSize?: 'large' | 'small' | 'default' | 'inherit';
+} | {
+    fontSize?: 'medium' | 'large' | 'small' | 'inherit';
+}>;
+
+export { AnalyticsApi, AnalyticsContext, AnalyticsContextValue, AnalyticsEvent, AnalyticsEventAttributes, AnalyticsTracker, AnyExtensionDataMap, AnyExtensionInputMap, AnyExternalRoutes, AnyRouteRefParams, AnyRoutes, AppNode, AppNodeEdges, AppNodeInstance, AppNodeSpec, AppTree, AppTreeApi, BackstagePlugin, CommonAnalyticsContext, ComponentRef, ComponentsApi, ConfigurableExtensionDataRef, CoreBootErrorPageComponent, CoreErrorBoundaryFallbackComponent, CoreNotFoundErrorPageComponent, CoreProgressComponent, CreateExtensionOptions, Extension, ExtensionBoundary, ExtensionBoundaryProps, ExtensionDataRef, ExtensionDataValues, ExtensionInput, ExtensionInputValues, ExtensionOverrides, ExtensionOverridesOptions, ExternalRouteRef, FeatureFlagConfig, IconComponent, LogoElements, NavTarget, PluginOptions, PortableSchema, RouteFunc, RouteRef, SubRouteRef, analyticsApiRef, appTreeApiRef, componentsApiRef, coreComponentsRefs, coreExtensionData, createApiExtension, createComponentExtension, createExtension, createExtensionDataRef, createExtensionInput, createExtensionOverrides, createExternalRouteRef, createNavItemExtension, createPageExtension, createPlugin, createRouteRef, createSchemaFromZod, createSignInPageExtension, createSubRouteRef, createThemeExtension, useAnalytics, useRouteRef, useRouteRefParams };