@backstage/frontend-plugin-api 0.11.0-next.0 → 0.11.0-next.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +211 -0
- package/dist/analytics/useAnalytics.esm.js +1 -1
- package/dist/apis/definitions/AnalyticsApi.esm.js.map +1 -1
- package/dist/apis/definitions/AppTreeApi.esm.js.map +1 -1
- package/dist/apis/definitions/DialogApi.esm.js.map +1 -1
- package/dist/apis/definitions/RouteResolutionApi.esm.js.map +1 -1
- package/dist/apis/definitions/SwappableComponentsApi.esm.js +8 -0
- package/dist/apis/definitions/SwappableComponentsApi.esm.js.map +1 -0
- package/dist/blueprints/AnalyticsImplementationBlueprint.esm.js +24 -0
- package/dist/blueprints/AnalyticsImplementationBlueprint.esm.js.map +1 -0
- package/dist/blueprints/AppRootElementBlueprint.esm.js +1 -3
- package/dist/blueprints/AppRootElementBlueprint.esm.js.map +1 -1
- package/dist/blueprints/AppRootWrapperBlueprint.esm.js +1 -5
- package/dist/blueprints/AppRootWrapperBlueprint.esm.js.map +1 -1
- package/dist/blueprints/PageBlueprint.esm.js +17 -9
- package/dist/blueprints/PageBlueprint.esm.js.map +1 -1
- package/dist/blueprints/RouterBlueprint.esm.js +2 -2
- package/dist/blueprints/RouterBlueprint.esm.js.map +1 -1
- package/dist/blueprints/SignInPageBlueprint.esm.js +9 -1
- package/dist/blueprints/SignInPageBlueprint.esm.js.map +1 -1
- package/dist/blueprints/SwappableComponentBlueprint.esm.js +27 -0
- package/dist/blueprints/SwappableComponentBlueprint.esm.js.map +1 -0
- package/dist/components/DefaultSwappableComponents.esm.js +16 -0
- package/dist/components/DefaultSwappableComponents.esm.js.map +1 -0
- package/dist/components/ErrorBoundary.esm.js +3 -2
- package/dist/components/ErrorBoundary.esm.js.map +1 -1
- package/dist/components/ExtensionBoundary.esm.js +9 -16
- package/dist/components/ExtensionBoundary.esm.js.map +1 -1
- package/dist/components/createSwappableComponent.esm.js +52 -0
- package/dist/components/createSwappableComponent.esm.js.map +1 -0
- package/dist/frontend-internal/src/wiring/InternalExtensionDefinition.esm.js.map +1 -1
- package/dist/frontend-internal/src/wiring/InternalSwappableComponentRef.esm.js +9 -0
- package/dist/frontend-internal/src/wiring/InternalSwappableComponentRef.esm.js.map +1 -0
- package/dist/frontend-internal/src/wiring/createExtensionDataContainer.esm.js +4 -1
- package/dist/frontend-internal/src/wiring/createExtensionDataContainer.esm.js.map +1 -1
- package/dist/index.d.ts +493 -294
- package/dist/index.esm.js +5 -4
- package/dist/index.esm.js.map +1 -1
- package/dist/routing/RouteRef.esm.js +8 -2
- package/dist/routing/RouteRef.esm.js.map +1 -1
- package/dist/routing/useRouteRef.esm.js +1 -1
- package/dist/wiring/createExtension.esm.js +7 -0
- package/dist/wiring/createExtension.esm.js.map +1 -1
- package/dist/wiring/createExtensionBlueprint.esm.js +3 -2
- package/dist/wiring/createExtensionBlueprint.esm.js.map +1 -1
- package/dist/wiring/createExtensionDataRef.esm.js.map +1 -1
- package/dist/wiring/createFrontendModule.esm.js.map +1 -1
- package/dist/wiring/createFrontendPlugin.esm.js +2 -6
- package/dist/wiring/createFrontendPlugin.esm.js.map +1 -1
- package/dist/wiring/resolveExtensionDefinition.esm.js.map +1 -1
- package/dist/wiring/resolveInputOverrides.esm.js +3 -0
- package/dist/wiring/resolveInputOverrides.esm.js.map +1 -1
- package/package.json +5 -5
- package/dist/apis/definitions/ComponentsApi.esm.js +0 -12
- package/dist/apis/definitions/ComponentsApi.esm.js.map +0 -1
- package/dist/components/coreComponentRefs.esm.js +0 -19
- package/dist/components/coreComponentRefs.esm.js.map +0 -1
- package/dist/components/createComponentRef.esm.js +0 -12
- package/dist/components/createComponentRef.esm.js.map +0 -1
- package/dist/extensions/createComponentExtension.esm.js +0 -43
- package/dist/extensions/createComponentExtension.esm.js.map +0 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
2
2
|
import * as react from 'react';
|
|
3
|
-
import { ReactNode, JSX as JSX$1, ComponentType
|
|
3
|
+
import { ReactNode, JSX as JSX$1, ComponentType } from 'react';
|
|
4
4
|
import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
|
|
5
|
-
import { ApiHolder, ConfigApi, ApiRef, ApiFactory, AnyApiFactory, IconComponent as IconComponent$2, SignInPageProps, AppTheme } from '@backstage/core-plugin-api';
|
|
5
|
+
import { ApiHolder, ConfigApi, ApiRef, TypesToApiRefs, ApiFactory, AnyApiFactory, IconComponent as IconComponent$2, SignInPageProps, AppTheme } from '@backstage/core-plugin-api';
|
|
6
6
|
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, vmwareCloudAuthApiRef, withApis } from '@backstage/core-plugin-api';
|
|
7
7
|
import { Expand, JsonObject } from '@backstage/types';
|
|
8
8
|
import { z } from 'zod';
|
|
@@ -12,11 +12,11 @@ import { TranslationResource, TranslationMessages } from '@backstage/core-plugin
|
|
|
12
12
|
export { TranslationMessages, TranslationMessagesOptions, TranslationRef, TranslationRefOptions, TranslationResource, TranslationResourceOptions, createTranslationMessages, createTranslationRef, createTranslationResource, useTranslationRef } from '@backstage/core-plugin-api/alpha';
|
|
13
13
|
|
|
14
14
|
/**
|
|
15
|
-
*
|
|
15
|
+
* Analytics context envelope.
|
|
16
16
|
*
|
|
17
17
|
* @public
|
|
18
18
|
*/
|
|
19
|
-
|
|
19
|
+
interface AnalyticsContextValue {
|
|
20
20
|
/**
|
|
21
21
|
* The nearest known parent plugin where the event was captured.
|
|
22
22
|
*/
|
|
@@ -25,15 +25,8 @@ type CommonAnalyticsContext = {
|
|
|
25
25
|
* The nearest known parent extension where the event was captured.
|
|
26
26
|
*/
|
|
27
27
|
extensionId: string;
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
* Analytics context envelope.
|
|
31
|
-
*
|
|
32
|
-
* @public
|
|
33
|
-
*/
|
|
34
|
-
type AnalyticsContextValue = CommonAnalyticsContext & {
|
|
35
|
-
[param in string]: string | boolean | number | undefined;
|
|
36
|
-
};
|
|
28
|
+
[key: string]: string | boolean | number | undefined;
|
|
29
|
+
}
|
|
37
30
|
|
|
38
31
|
/**
|
|
39
32
|
* Provides components in the child react tree an Analytics Context, ensuring
|
|
@@ -58,9 +51,11 @@ type ExtensionDataValue<TData, TId extends string> = {
|
|
|
58
51
|
readonly value: TData;
|
|
59
52
|
};
|
|
60
53
|
/** @public */
|
|
61
|
-
type ExtensionDataRef<TData, TId extends string = string, TConfig extends {
|
|
54
|
+
type ExtensionDataRef<TData = unknown, TId extends string = string, TConfig extends {
|
|
62
55
|
optional?: true;
|
|
63
|
-
} = {
|
|
56
|
+
} = {
|
|
57
|
+
optional?: true;
|
|
58
|
+
}> = {
|
|
64
59
|
readonly $$type: '@backstage/ExtensionDataRef';
|
|
65
60
|
readonly id: TId;
|
|
66
61
|
readonly T: TData;
|
|
@@ -68,10 +63,11 @@ type ExtensionDataRef<TData, TId extends string = string, TConfig extends {
|
|
|
68
63
|
};
|
|
69
64
|
/** @public */
|
|
70
65
|
type ExtensionDataRefToValue<TDataRef extends AnyExtensionDataRef> = TDataRef extends ExtensionDataRef<infer IData, infer IId, any> ? ExtensionDataValue<IData, IId> : never;
|
|
71
|
-
/**
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
66
|
+
/**
|
|
67
|
+
* @deprecated Use `ExtensionDataRef` without type parameters instead.
|
|
68
|
+
* @public
|
|
69
|
+
*/
|
|
70
|
+
type AnyExtensionDataRef = ExtensionDataRef;
|
|
75
71
|
/** @public */
|
|
76
72
|
interface ConfigurableExtensionDataRef<TData, TId extends string, TConfig extends {
|
|
77
73
|
optional?: true;
|
|
@@ -120,7 +116,8 @@ declare function createRouteRef<TParams extends {
|
|
|
120
116
|
[param in TParamKeys]: string;
|
|
121
117
|
} | undefined = undefined, TParamKeys extends string = string>(config?: {
|
|
122
118
|
/** A list of parameter names that the path that this route ref is bound to must contain */
|
|
123
|
-
readonly params
|
|
119
|
+
readonly params?: string extends TParamKeys ? (keyof TParams)[] : TParamKeys[];
|
|
120
|
+
aliasFor?: string;
|
|
124
121
|
}): RouteRef<keyof TParams extends never ? undefined : string extends TParamKeys ? TParams : {
|
|
125
122
|
[param in TParamKeys]: string;
|
|
126
123
|
}>;
|
|
@@ -163,14 +160,14 @@ declare function createExtensionInput<UExtensionData extends ExtensionDataRef<un
|
|
|
163
160
|
optional: TConfig['optional'] extends true ? true : false;
|
|
164
161
|
}>;
|
|
165
162
|
|
|
166
|
-
/** @
|
|
167
|
-
type
|
|
168
|
-
[inputName in string]: ExtensionInput<
|
|
163
|
+
/** @ignore */
|
|
164
|
+
type ResolvedInputValueOverrides<TInputs extends {
|
|
165
|
+
[inputName in string]: ExtensionInput<ExtensionDataRef, {
|
|
169
166
|
optional: boolean;
|
|
170
167
|
singleton: boolean;
|
|
171
168
|
}>;
|
|
172
169
|
} = {
|
|
173
|
-
[inputName in string]: ExtensionInput<
|
|
170
|
+
[inputName in string]: ExtensionInput<ExtensionDataRef, {
|
|
174
171
|
optional: boolean;
|
|
175
172
|
singleton: boolean;
|
|
176
173
|
}>;
|
|
@@ -192,6 +189,115 @@ type ResolveInputValueOverrides<TInputs extends {
|
|
|
192
189
|
}> ? ISingleton extends true ? Iterable<ExtensionDataRefToValue<IDataRefs>> : Array<Iterable<ExtensionDataRefToValue<IDataRefs>>> : never;
|
|
193
190
|
}>;
|
|
194
191
|
|
|
192
|
+
/** @public */
|
|
193
|
+
interface CreateFrontendModuleOptions<TPluginId extends string, TExtensions extends readonly ExtensionDefinition[]> {
|
|
194
|
+
pluginId: TPluginId;
|
|
195
|
+
extensions?: TExtensions;
|
|
196
|
+
featureFlags?: FeatureFlagConfig[];
|
|
197
|
+
}
|
|
198
|
+
/** @public */
|
|
199
|
+
interface FrontendModule {
|
|
200
|
+
readonly $$type: '@backstage/FrontendModule';
|
|
201
|
+
readonly pluginId: string;
|
|
202
|
+
}
|
|
203
|
+
/**
|
|
204
|
+
* Creates a new module that can be installed in a Backstage app.
|
|
205
|
+
*
|
|
206
|
+
* @remarks
|
|
207
|
+
*
|
|
208
|
+
* Modules are used to add or override extensions for an existing plugin. If a
|
|
209
|
+
* module provides an extension with the same ID as one provided by the plugin,
|
|
210
|
+
* the extension provided by the module will always take precedence.
|
|
211
|
+
*
|
|
212
|
+
* Every module is created for a specific plugin by providing the
|
|
213
|
+
* unique ID of the plugin that the module should be installed for. If that
|
|
214
|
+
* plugin is not present in the app, the module will be ignored and have no
|
|
215
|
+
* effect.
|
|
216
|
+
*
|
|
217
|
+
* For more information on how modules work, see the
|
|
218
|
+
* {@link https://backstage.io/docs/frontend-system/architecture/extension-overrides#creating-a-frontend-module | documentation for modules}
|
|
219
|
+
* in the frontend system documentation.
|
|
220
|
+
*
|
|
221
|
+
* It is recommended to name the module variable of the form `<pluginId>Module<ModuleName>`.
|
|
222
|
+
*
|
|
223
|
+
* @example
|
|
224
|
+
*
|
|
225
|
+
* ```tsx
|
|
226
|
+
* import { createFrontendModule } from '@backstage/frontend-plugin-api';
|
|
227
|
+
*
|
|
228
|
+
* export const exampleModuleCustomPage = createFrontendModule({
|
|
229
|
+
* pluginId: 'example',
|
|
230
|
+
* extensions: [
|
|
231
|
+
* // Overrides the default page for the 'example' plugin
|
|
232
|
+
* PageBlueprint.make({
|
|
233
|
+
* path: '/example',
|
|
234
|
+
* loader: () => import('./CustomPage').then(m => <m.CustomPage />),
|
|
235
|
+
* }),
|
|
236
|
+
* ],
|
|
237
|
+
* });
|
|
238
|
+
* ```
|
|
239
|
+
*
|
|
240
|
+
* @public
|
|
241
|
+
*/
|
|
242
|
+
declare function createFrontendModule<TId extends string, TExtensions extends readonly ExtensionDefinition[] = []>(options: CreateFrontendModuleOptions<TId, TExtensions>): FrontendModule;
|
|
243
|
+
|
|
244
|
+
/** @public */
|
|
245
|
+
type PortableSchema<TOutput, TInput = TOutput> = {
|
|
246
|
+
parse: (input: TInput) => TOutput;
|
|
247
|
+
schema: JsonObject;
|
|
248
|
+
};
|
|
249
|
+
|
|
250
|
+
/** @public */
|
|
251
|
+
interface Extension<TConfig, TConfigInput = TConfig> {
|
|
252
|
+
$$type: '@backstage/Extension';
|
|
253
|
+
readonly id: string;
|
|
254
|
+
readonly attachTo: ExtensionAttachToSpec;
|
|
255
|
+
readonly disabled: boolean;
|
|
256
|
+
readonly configSchema?: PortableSchema<TConfig, TConfigInput>;
|
|
257
|
+
}
|
|
258
|
+
/** @ignore */
|
|
259
|
+
type ResolveExtensionId<TExtension extends ExtensionDefinition, TNamespace extends string> = TExtension extends ExtensionDefinition<{
|
|
260
|
+
kind: infer IKind extends string | undefined;
|
|
261
|
+
name: infer IName extends string | undefined;
|
|
262
|
+
params: any;
|
|
263
|
+
}> ? [string] extends [IKind | IName] ? never : (undefined extends IName ? TNamespace : `${TNamespace}/${IName}`) extends infer INamePart extends string ? IKind extends string ? `${IKind}:${INamePart}` : INamePart : never : never;
|
|
264
|
+
|
|
265
|
+
type CompareChars<A extends string, B extends string> = [A, B] extends [
|
|
266
|
+
`${infer IAHead}${infer IARest}`,
|
|
267
|
+
`${infer IBHead}${infer IBRest}`
|
|
268
|
+
] ? IAHead extends IBHead ? IBRest extends '' ? IARest extends '' ? 'eq' : 'gt' : IARest extends '' ? 'lt' : CompareChars<IARest, IBRest> : `0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz` extends `${string}${IAHead}${string}${IBHead}${string}` ? 'lt' : 'gt' : 'eq';
|
|
269
|
+
type CompareStrings<A extends string | undefined, B extends string | undefined> = A extends B ? 'eq' : A extends undefined ? 'lt' : B extends undefined ? 'gt' : CompareChars<A & string, B & string>;
|
|
270
|
+
type CompareExtensions<A extends ExtensionDefinition, B extends ExtensionDefinition> = CompareStrings<A['T']['kind'], B['T']['kind']> extends 'eq' ? CompareStrings<A['T']['name'], B['T']['name']> : CompareStrings<A['T']['kind'], B['T']['kind']>;
|
|
271
|
+
type SortExtensionsInner<TPivot extends ExtensionDefinition, TRest extends readonly ExtensionDefinition[], TLow extends readonly ExtensionDefinition[], THigh extends readonly ExtensionDefinition[]> = TRest extends [
|
|
272
|
+
infer IHead extends ExtensionDefinition,
|
|
273
|
+
...infer IRest extends readonly ExtensionDefinition[]
|
|
274
|
+
] ? CompareExtensions<IHead, TPivot> extends 'lt' ? SortExtensionsInner<TPivot, IRest, [...TLow, IHead], THigh> : SortExtensionsInner<TPivot, IRest, TLow, [...THigh, IHead]> : [low: TLow, high: THigh];
|
|
275
|
+
type SortExtensions<T extends readonly ExtensionDefinition[]> = T extends [
|
|
276
|
+
infer IPivot extends ExtensionDefinition,
|
|
277
|
+
...infer IRest extends readonly ExtensionDefinition[]
|
|
278
|
+
] ? SortExtensionsInner<IPivot, IRest, [], []> extends [
|
|
279
|
+
low: infer ILow extends readonly ExtensionDefinition[],
|
|
280
|
+
high: infer IHigh extends readonly ExtensionDefinition[]
|
|
281
|
+
] ? [...SortExtensions<ILow>, IPivot, ...SortExtensions<IHigh>] : 'invalid SortExtensionsInner' : [];
|
|
282
|
+
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
|
|
283
|
+
type PopUnion$1<U> = UnionToIntersection<U extends any ? () => U : never> extends () => infer R ? [next: R, rest: Exclude<U, R>] : undefined;
|
|
284
|
+
type UnionToArray<U, T = U, TResult extends T[] = []> = PopUnion$1<U> extends [
|
|
285
|
+
next: infer INext extends T,
|
|
286
|
+
rest: infer IRest extends T
|
|
287
|
+
] ? UnionToArray<IRest, T, [INext, ...TResult]> : TResult;
|
|
288
|
+
type ExtensionArrayToMap<T extends ExtensionDefinition[], TId extends string, TOut extends {
|
|
289
|
+
[KId in string]: ExtensionDefinition;
|
|
290
|
+
} = {}> = T extends [
|
|
291
|
+
infer IHead extends ExtensionDefinition,
|
|
292
|
+
...infer IRest extends ExtensionDefinition[]
|
|
293
|
+
] ? ExtensionArrayToMap<IRest, TId, TOut & {
|
|
294
|
+
[K in ResolveExtensionId<IHead, TId>]: IHead;
|
|
295
|
+
}> : TOut extends infer O ? {
|
|
296
|
+
[K in keyof O]: O[K];
|
|
297
|
+
} : never;
|
|
298
|
+
/** @ignore */
|
|
299
|
+
type MakeSortedExtensionsMap<UExtensions extends ExtensionDefinition, TId extends string> = ExtensionArrayToMap<SortExtensions<UnionToArray<UExtensions>>, TId>;
|
|
300
|
+
|
|
195
301
|
/**
|
|
196
302
|
* Descriptor of a route relative to an absolute {@link RouteRef}.
|
|
197
303
|
*
|
|
@@ -319,77 +425,6 @@ declare function useRouteRef<TParams extends AnyRouteRefParams>(routeRef: RouteR
|
|
|
319
425
|
*/
|
|
320
426
|
declare function useRouteRefParams<Params extends AnyRouteRefParams>(_routeRef: RouteRef<Params> | SubRouteRef<Params>): Params;
|
|
321
427
|
|
|
322
|
-
/** @public */
|
|
323
|
-
interface CreateFrontendModuleOptions<TPluginId extends string, TExtensions extends readonly ExtensionDefinition[]> {
|
|
324
|
-
pluginId: TPluginId;
|
|
325
|
-
extensions?: TExtensions;
|
|
326
|
-
featureFlags?: FeatureFlagConfig[];
|
|
327
|
-
}
|
|
328
|
-
/** @public */
|
|
329
|
-
interface FrontendModule {
|
|
330
|
-
readonly $$type: '@backstage/FrontendModule';
|
|
331
|
-
readonly pluginId: string;
|
|
332
|
-
}
|
|
333
|
-
/** @public */
|
|
334
|
-
declare function createFrontendModule<TId extends string, TExtensions extends readonly ExtensionDefinition[] = []>(options: CreateFrontendModuleOptions<TId, TExtensions>): FrontendModule;
|
|
335
|
-
|
|
336
|
-
/** @public */
|
|
337
|
-
type PortableSchema<TOutput, TInput = TOutput> = {
|
|
338
|
-
parse: (input: TInput) => TOutput;
|
|
339
|
-
schema: JsonObject;
|
|
340
|
-
};
|
|
341
|
-
|
|
342
|
-
/** @public */
|
|
343
|
-
interface Extension<TConfig, TConfigInput = TConfig> {
|
|
344
|
-
$$type: '@backstage/Extension';
|
|
345
|
-
readonly id: string;
|
|
346
|
-
readonly attachTo: ExtensionAttachToSpec;
|
|
347
|
-
readonly disabled: boolean;
|
|
348
|
-
readonly configSchema?: PortableSchema<TConfig, TConfigInput>;
|
|
349
|
-
}
|
|
350
|
-
/** @ignore */
|
|
351
|
-
type ResolveExtensionId<TExtension extends ExtensionDefinition, TNamespace extends string> = TExtension extends ExtensionDefinition<{
|
|
352
|
-
kind: infer IKind extends string | undefined;
|
|
353
|
-
name: infer IName extends string | undefined;
|
|
354
|
-
params: any;
|
|
355
|
-
}> ? [string] extends [IKind | IName] ? never : (undefined extends IName ? TNamespace : `${TNamespace}/${IName}`) extends infer INamePart extends string ? IKind extends string ? `${IKind}:${INamePart}` : INamePart : never : never;
|
|
356
|
-
|
|
357
|
-
type CompareChars<A extends string, B extends string> = [A, B] extends [
|
|
358
|
-
`${infer IAHead}${infer IARest}`,
|
|
359
|
-
`${infer IBHead}${infer IBRest}`
|
|
360
|
-
] ? IAHead extends IBHead ? IBRest extends '' ? IARest extends '' ? 'eq' : 'gt' : IARest extends '' ? 'lt' : CompareChars<IARest, IBRest> : `0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz` extends `${string}${IAHead}${string}${IBHead}${string}` ? 'lt' : 'gt' : 'eq';
|
|
361
|
-
type CompareStrings<A extends string | undefined, B extends string | undefined> = A extends B ? 'eq' : A extends undefined ? 'lt' : B extends undefined ? 'gt' : CompareChars<A & string, B & string>;
|
|
362
|
-
type CompareExtensions<A extends ExtensionDefinition, B extends ExtensionDefinition> = CompareStrings<A['T']['kind'], B['T']['kind']> extends 'eq' ? CompareStrings<A['T']['name'], B['T']['name']> : CompareStrings<A['T']['kind'], B['T']['kind']>;
|
|
363
|
-
type SortExtensionsInner<TPivot extends ExtensionDefinition, TRest extends readonly ExtensionDefinition[], TLow extends readonly ExtensionDefinition[], THigh extends readonly ExtensionDefinition[]> = TRest extends [
|
|
364
|
-
infer IHead extends ExtensionDefinition,
|
|
365
|
-
...infer IRest extends readonly ExtensionDefinition[]
|
|
366
|
-
] ? CompareExtensions<IHead, TPivot> extends 'lt' ? SortExtensionsInner<TPivot, IRest, [...TLow, IHead], THigh> : SortExtensionsInner<TPivot, IRest, TLow, [...THigh, IHead]> : [low: TLow, high: THigh];
|
|
367
|
-
type SortExtensions<T extends readonly ExtensionDefinition[]> = T extends [
|
|
368
|
-
infer IPivot extends ExtensionDefinition,
|
|
369
|
-
...infer IRest extends readonly ExtensionDefinition[]
|
|
370
|
-
] ? SortExtensionsInner<IPivot, IRest, [], []> extends [
|
|
371
|
-
low: infer ILow extends readonly ExtensionDefinition[],
|
|
372
|
-
high: infer IHigh extends readonly ExtensionDefinition[]
|
|
373
|
-
] ? [...SortExtensions<ILow>, IPivot, ...SortExtensions<IHigh>] : 'invalid SortExtensionsInner' : [];
|
|
374
|
-
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
|
|
375
|
-
type PopUnion$1<U> = UnionToIntersection<U extends any ? () => U : never> extends () => infer R ? [next: R, rest: Exclude<U, R>] : undefined;
|
|
376
|
-
type UnionToArray<U, T = U, TResult extends T[] = []> = PopUnion$1<U> extends [
|
|
377
|
-
next: infer INext extends T,
|
|
378
|
-
rest: infer IRest extends T
|
|
379
|
-
] ? UnionToArray<IRest, T, [INext, ...TResult]> : TResult;
|
|
380
|
-
type ExtensionArrayToMap<T extends ExtensionDefinition[], TId extends string, TOut extends {
|
|
381
|
-
[KId in string]: ExtensionDefinition;
|
|
382
|
-
} = {}> = T extends [
|
|
383
|
-
infer IHead extends ExtensionDefinition,
|
|
384
|
-
...infer IRest extends ExtensionDefinition[]
|
|
385
|
-
] ? ExtensionArrayToMap<IRest, TId, TOut & {
|
|
386
|
-
[K in ResolveExtensionId<IHead, TId>]: IHead;
|
|
387
|
-
}> : TOut extends infer O ? {
|
|
388
|
-
[K in keyof O]: O[K];
|
|
389
|
-
} : never;
|
|
390
|
-
/** @ignore */
|
|
391
|
-
type MakeSortedExtensionsMap<UExtensions extends ExtensionDefinition, TId extends string> = ExtensionArrayToMap<SortExtensions<UnionToArray<UExtensions>>, TId>;
|
|
392
|
-
|
|
393
428
|
/**
|
|
394
429
|
* Information about the plugin.
|
|
395
430
|
*
|
|
@@ -450,7 +485,15 @@ type FrontendPluginInfoOptions = {
|
|
|
450
485
|
manifest?: () => Promise<JsonObject>;
|
|
451
486
|
};
|
|
452
487
|
/** @public */
|
|
453
|
-
interface FrontendPlugin<TRoutes extends
|
|
488
|
+
interface FrontendPlugin<TRoutes extends {
|
|
489
|
+
[name in string]: RouteRef | SubRouteRef;
|
|
490
|
+
} = {
|
|
491
|
+
[name in string]: RouteRef | SubRouteRef;
|
|
492
|
+
}, TExternalRoutes extends {
|
|
493
|
+
[name in string]: ExternalRouteRef;
|
|
494
|
+
} = {
|
|
495
|
+
[name in string]: ExternalRouteRef;
|
|
496
|
+
}, TExtensionMap extends {
|
|
454
497
|
[id in string]: ExtensionDefinition;
|
|
455
498
|
} = {
|
|
456
499
|
[id in string]: ExtensionDefinition;
|
|
@@ -473,7 +516,11 @@ interface FrontendPlugin<TRoutes extends AnyRoutes = AnyRoutes, TExternalRoutes
|
|
|
473
516
|
}): FrontendPlugin<TRoutes, TExternalRoutes, TExtensionMap>;
|
|
474
517
|
}
|
|
475
518
|
/** @public */
|
|
476
|
-
interface PluginOptions<TId extends string, TRoutes extends
|
|
519
|
+
interface PluginOptions<TId extends string, TRoutes extends {
|
|
520
|
+
[name in string]: RouteRef | SubRouteRef;
|
|
521
|
+
}, TExternalRoutes extends {
|
|
522
|
+
[name in string]: ExternalRouteRef;
|
|
523
|
+
}, TExtensions extends readonly ExtensionDefinition[]> {
|
|
477
524
|
pluginId: TId;
|
|
478
525
|
routes?: TRoutes;
|
|
479
526
|
externalRoutes?: TExternalRoutes;
|
|
@@ -481,15 +528,41 @@ interface PluginOptions<TId extends string, TRoutes extends AnyRoutes, TExternal
|
|
|
481
528
|
featureFlags?: FeatureFlagConfig[];
|
|
482
529
|
info?: FrontendPluginInfoOptions;
|
|
483
530
|
}
|
|
484
|
-
/** @public */
|
|
485
|
-
declare function createFrontendPlugin<TId extends string, TRoutes extends AnyRoutes = {}, TExternalRoutes extends AnyExternalRoutes = {}, TExtensions extends readonly ExtensionDefinition[] = []>(options: PluginOptions<TId, TRoutes, TExternalRoutes, TExtensions>): FrontendPlugin<TRoutes, TExternalRoutes, MakeSortedExtensionsMap<TExtensions[number], TId>>;
|
|
486
531
|
/**
|
|
532
|
+
* Creates a new plugin that can be installed in a Backstage app.
|
|
533
|
+
*
|
|
534
|
+
* @remarks
|
|
535
|
+
*
|
|
536
|
+
* Every plugin is created with a unique ID and a set of extensions
|
|
537
|
+
* that are installed as part of the plugin.
|
|
538
|
+
*
|
|
539
|
+
* For more information on how plugins work, see the
|
|
540
|
+
* {@link https://backstage.io/docs/frontend-system/building-plugins/index | documentation for plugins}
|
|
541
|
+
* in the frontend system documentation.
|
|
542
|
+
*
|
|
543
|
+
* @example
|
|
544
|
+
*
|
|
545
|
+
* ```tsx
|
|
546
|
+
* import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
|
|
547
|
+
*
|
|
548
|
+
* export const examplePlugin = createFrontendPlugin({
|
|
549
|
+
* pluginId: 'example',
|
|
550
|
+
* extensions: [
|
|
551
|
+
* PageBlueprint.make({
|
|
552
|
+
* path: '/example',
|
|
553
|
+
* loader: () => import('./ExamplePage').then(m => <m.ExamplePage />),
|
|
554
|
+
* }),
|
|
555
|
+
* ],
|
|
556
|
+
* });
|
|
557
|
+
* ```
|
|
558
|
+
*
|
|
487
559
|
* @public
|
|
488
|
-
* @deprecated The `id` option is deprecated, use `pluginId` instead.
|
|
489
560
|
*/
|
|
490
|
-
declare function createFrontendPlugin<TId extends string, TRoutes extends
|
|
491
|
-
|
|
492
|
-
}
|
|
561
|
+
declare function createFrontendPlugin<TId extends string, TRoutes extends {
|
|
562
|
+
[name in string]: RouteRef | SubRouteRef;
|
|
563
|
+
} = {}, TExternalRoutes extends {
|
|
564
|
+
[name in string]: ExternalRouteRef;
|
|
565
|
+
} = {}, TExtensions extends readonly ExtensionDefinition[] = []>(options: PluginOptions<TId, TRoutes, TExternalRoutes, TExtensions>): FrontendPlugin<TRoutes, TExternalRoutes, MakeSortedExtensionsMap<TExtensions[number], TId>>;
|
|
493
566
|
|
|
494
567
|
/**
|
|
495
568
|
* Feature flag configuration.
|
|
@@ -501,21 +574,13 @@ type FeatureFlagConfig = {
|
|
|
501
574
|
name: string;
|
|
502
575
|
};
|
|
503
576
|
/** @public */
|
|
504
|
-
type
|
|
505
|
-
[name in string]: RouteRef | SubRouteRef;
|
|
506
|
-
};
|
|
507
|
-
/** @public */
|
|
508
|
-
type AnyExternalRoutes = {
|
|
509
|
-
[name in string]: ExternalRouteRef;
|
|
510
|
-
};
|
|
511
|
-
/** @public */
|
|
512
|
-
type ExtensionDataContainer<UExtensionData extends AnyExtensionDataRef> = Iterable<UExtensionData extends ExtensionDataRef<infer IData, infer IId, infer IConfig> ? IConfig['optional'] extends true ? never : ExtensionDataValue<IData, IId> : never> & {
|
|
577
|
+
type ExtensionDataContainer<UExtensionData extends ExtensionDataRef> = Iterable<UExtensionData extends ExtensionDataRef<infer IData, infer IId, infer IConfig> ? IConfig['optional'] extends true ? never : ExtensionDataValue<IData, IId> : never> & {
|
|
513
578
|
get<TId extends UExtensionData['id']>(ref: ExtensionDataRef<any, TId, any>): UExtensionData extends ExtensionDataRef<infer IData, TId, infer IConfig> ? IConfig['optional'] extends true ? IData | undefined : IData : never;
|
|
514
579
|
};
|
|
515
580
|
/** @public */
|
|
516
581
|
type ExtensionFactoryMiddleware = (originalFactory: (contextOverrides?: {
|
|
517
582
|
config?: JsonObject;
|
|
518
|
-
}) => ExtensionDataContainer<
|
|
583
|
+
}) => ExtensionDataContainer<ExtensionDataRef>, context: {
|
|
519
584
|
node: AppNode;
|
|
520
585
|
apis: ApiHolder;
|
|
521
586
|
config?: JsonObject;
|
|
@@ -538,7 +603,7 @@ type FrontendFeature = FrontendPlugin | FrontendModule;
|
|
|
538
603
|
*
|
|
539
604
|
* @public
|
|
540
605
|
*/
|
|
541
|
-
type
|
|
606
|
+
type ExtensionBlueprintDefineParams<TParams extends object = object, TInput = any> = (params: TInput) => ExtensionBlueprintParams<TParams>;
|
|
542
607
|
/**
|
|
543
608
|
* An opaque type that represents a set of parameters to be passed to a blueprint.
|
|
544
609
|
*
|
|
@@ -565,22 +630,21 @@ declare function createExtensionBlueprintParams<T extends object = object>(param
|
|
|
565
630
|
/**
|
|
566
631
|
* @public
|
|
567
632
|
*/
|
|
568
|
-
type CreateExtensionBlueprintOptions<TKind extends string,
|
|
569
|
-
[inputName in string]: ExtensionInput<
|
|
633
|
+
type CreateExtensionBlueprintOptions<TKind extends string, TParams extends object | ExtensionBlueprintDefineParams, UOutput extends ExtensionDataRef, TInputs extends {
|
|
634
|
+
[inputName in string]: ExtensionInput<ExtensionDataRef, {
|
|
570
635
|
optional: boolean;
|
|
571
636
|
singleton: boolean;
|
|
572
637
|
}>;
|
|
573
638
|
}, TConfigSchema extends {
|
|
574
639
|
[key in string]: (zImpl: typeof z) => z.ZodType;
|
|
575
640
|
}, UFactoryOutput extends ExtensionDataValue<any, any>, TDataRefs extends {
|
|
576
|
-
[name in string]:
|
|
641
|
+
[name in string]: ExtensionDataRef;
|
|
577
642
|
}> = {
|
|
578
643
|
kind: TKind;
|
|
579
644
|
attachTo: ExtensionAttachToSpec;
|
|
580
645
|
disabled?: boolean;
|
|
581
646
|
inputs?: TInputs;
|
|
582
647
|
output: Array<UOutput>;
|
|
583
|
-
name?: TName;
|
|
584
648
|
config?: {
|
|
585
649
|
schema: TConfigSchema;
|
|
586
650
|
};
|
|
@@ -615,15 +679,15 @@ type CreateExtensionBlueprintOptions<TKind extends string, TName extends string
|
|
|
615
679
|
* Usage of the above example blueprint:
|
|
616
680
|
* ```ts
|
|
617
681
|
* const example = ExampleBlueprint.make({
|
|
618
|
-
* params:
|
|
682
|
+
* params: defineParams => defineParams({
|
|
619
683
|
* component: ...,
|
|
620
684
|
* fetcher: ...,
|
|
621
685
|
* }),
|
|
622
686
|
* });
|
|
623
687
|
* ```
|
|
624
688
|
*/
|
|
625
|
-
defineParams?: TParams extends
|
|
626
|
-
factory(params: TParams extends
|
|
689
|
+
defineParams?: TParams extends ExtensionBlueprintDefineParams ? TParams : 'The defineParams option must be a function if provided, see the docs for details';
|
|
690
|
+
factory(params: TParams extends ExtensionBlueprintDefineParams ? ReturnType<TParams>['T'] : TParams, context: {
|
|
627
691
|
node: AppNode;
|
|
628
692
|
apis: ApiHolder;
|
|
629
693
|
config: {
|
|
@@ -636,47 +700,46 @@ type CreateExtensionBlueprintOptions<TKind extends string, TName extends string
|
|
|
636
700
|
/** @public */
|
|
637
701
|
type ExtensionBlueprintParameters = {
|
|
638
702
|
kind: string;
|
|
639
|
-
|
|
640
|
-
params?: object | ExtensionBlueprintParamsDefiner;
|
|
703
|
+
params?: object | ExtensionBlueprintDefineParams;
|
|
641
704
|
configInput?: {
|
|
642
705
|
[K in string]: any;
|
|
643
706
|
};
|
|
644
707
|
config?: {
|
|
645
708
|
[K in string]: any;
|
|
646
709
|
};
|
|
647
|
-
output?:
|
|
710
|
+
output?: ExtensionDataRef;
|
|
648
711
|
inputs?: {
|
|
649
|
-
[KName in string]: ExtensionInput<
|
|
712
|
+
[KName in string]: ExtensionInput<ExtensionDataRef, {
|
|
650
713
|
optional: boolean;
|
|
651
714
|
singleton: boolean;
|
|
652
715
|
}>;
|
|
653
716
|
};
|
|
654
717
|
dataRefs?: {
|
|
655
|
-
[name in string]:
|
|
718
|
+
[name in string]: ExtensionDataRef;
|
|
656
719
|
};
|
|
657
720
|
};
|
|
658
721
|
/** @ignore */
|
|
659
|
-
type ParamsFactory<TDefiner extends
|
|
722
|
+
type ParamsFactory<TDefiner extends ExtensionBlueprintDefineParams> = (defineParams: TDefiner) => ReturnType<TDefiner>;
|
|
660
723
|
/**
|
|
661
724
|
* Represents any form of params input that can be passed to a blueprint.
|
|
662
725
|
* This also includes the invalid form of passing a plain params object to a blueprint that uses a definition callback.
|
|
663
726
|
*
|
|
664
727
|
* @ignore
|
|
665
728
|
*/
|
|
666
|
-
type AnyParamsInput$1<TParams extends object |
|
|
729
|
+
type AnyParamsInput$1<TParams extends object | ExtensionBlueprintDefineParams> = TParams extends ExtensionBlueprintDefineParams<infer IParams> ? IParams | ParamsFactory<TParams> : TParams | ParamsFactory<ExtensionBlueprintDefineParams<TParams, TParams>>;
|
|
667
730
|
/**
|
|
668
731
|
* @public
|
|
669
732
|
*/
|
|
670
733
|
interface ExtensionBlueprint<T extends ExtensionBlueprintParameters = ExtensionBlueprintParameters> {
|
|
671
734
|
dataRefs: T['dataRefs'];
|
|
672
|
-
make<
|
|
673
|
-
name?:
|
|
735
|
+
make<TName extends string | undefined, TParamsInput extends AnyParamsInput$1<NonNullable<T['params']>>>(args: {
|
|
736
|
+
name?: TName;
|
|
674
737
|
attachTo?: ExtensionAttachToSpec;
|
|
675
738
|
disabled?: boolean;
|
|
676
|
-
params: TParamsInput extends
|
|
739
|
+
params: TParamsInput extends ExtensionBlueprintDefineParams ? TParamsInput : T['params'] extends ExtensionBlueprintDefineParams ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `<blueprint>.make({ params: defineParams => defineParams(<params>) })`' : T['params'];
|
|
677
740
|
}): ExtensionDefinition<{
|
|
678
741
|
kind: T['kind'];
|
|
679
|
-
name: string | undefined extends
|
|
742
|
+
name: string | undefined extends TName ? undefined : TName;
|
|
680
743
|
config: T['config'];
|
|
681
744
|
configInput: T['configInput'];
|
|
682
745
|
output: T['output'];
|
|
@@ -689,15 +752,15 @@ interface ExtensionBlueprint<T extends ExtensionBlueprintParameters = ExtensionB
|
|
|
689
752
|
* You must either pass `params` directly, or define a `factory` that can
|
|
690
753
|
* optionally call the original factory with the same params.
|
|
691
754
|
*/
|
|
692
|
-
makeWithOverrides<
|
|
755
|
+
makeWithOverrides<TName extends string | undefined, TExtensionConfigSchema extends {
|
|
693
756
|
[key in string]: (zImpl: typeof z) => z.ZodType;
|
|
694
|
-
}, UFactoryOutput extends ExtensionDataValue<any, any>, UNewOutput extends
|
|
695
|
-
[inputName in string]: ExtensionInput<
|
|
757
|
+
}, UFactoryOutput extends ExtensionDataValue<any, any>, UNewOutput extends ExtensionDataRef, TExtraInputs extends {
|
|
758
|
+
[inputName in string]: ExtensionInput<ExtensionDataRef, {
|
|
696
759
|
optional: boolean;
|
|
697
760
|
singleton: boolean;
|
|
698
761
|
}>;
|
|
699
762
|
}>(args: {
|
|
700
|
-
name?:
|
|
763
|
+
name?: TName;
|
|
701
764
|
attachTo?: ExtensionAttachToSpec;
|
|
702
765
|
disabled?: boolean;
|
|
703
766
|
inputs?: TExtraInputs & {
|
|
@@ -709,9 +772,9 @@ interface ExtensionBlueprint<T extends ExtensionBlueprintParameters = ExtensionB
|
|
|
709
772
|
[KName in keyof T['config']]?: `Error: Config key '${KName & string}' is already defined in parent schema`;
|
|
710
773
|
};
|
|
711
774
|
};
|
|
712
|
-
factory(originalFactory: <TParamsInput extends AnyParamsInput$1<NonNullable<T['params']>>>(params: TParamsInput extends
|
|
775
|
+
factory(originalFactory: <TParamsInput extends AnyParamsInput$1<NonNullable<T['params']>>>(params: TParamsInput extends ExtensionBlueprintDefineParams ? TParamsInput : T['params'] extends ExtensionBlueprintDefineParams ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `originalFactory(defineParams => defineParams(<params>))`' : T['params'], context?: {
|
|
713
776
|
config?: T['config'];
|
|
714
|
-
inputs?:
|
|
777
|
+
inputs?: ResolvedInputValueOverrides<NonNullable<T['inputs']>>;
|
|
715
778
|
}) => ExtensionDataContainer<NonNullable<T['output']>>, context: {
|
|
716
779
|
node: AppNode;
|
|
717
780
|
apis: ApiHolder;
|
|
@@ -719,7 +782,7 @@ interface ExtensionBlueprint<T extends ExtensionBlueprintParameters = ExtensionB
|
|
|
719
782
|
[key in keyof TExtensionConfigSchema]: z.infer<ReturnType<TExtensionConfigSchema[key]>>;
|
|
720
783
|
};
|
|
721
784
|
inputs: Expand<ResolvedExtensionInputs<T['inputs'] & TExtraInputs>>;
|
|
722
|
-
}): Iterable<UFactoryOutput> & VerifyExtensionFactoryOutput<
|
|
785
|
+
}): Iterable<UFactoryOutput> & VerifyExtensionFactoryOutput<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UFactoryOutput>;
|
|
723
786
|
}): ExtensionDefinition<{
|
|
724
787
|
config: (string extends keyof TExtensionConfigSchema ? {} : {
|
|
725
788
|
[key in keyof TExtensionConfigSchema]: z.infer<ReturnType<TExtensionConfigSchema[key]>>;
|
|
@@ -727,33 +790,75 @@ interface ExtensionBlueprint<T extends ExtensionBlueprintParameters = ExtensionB
|
|
|
727
790
|
configInput: (string extends keyof TExtensionConfigSchema ? {} : z.input<z.ZodObject<{
|
|
728
791
|
[key in keyof TExtensionConfigSchema]: ReturnType<TExtensionConfigSchema[key]>;
|
|
729
792
|
}>>) & T['configInput'];
|
|
730
|
-
output:
|
|
793
|
+
output: ExtensionDataRef extends UNewOutput ? T['output'] : UNewOutput;
|
|
731
794
|
inputs: T['inputs'] & TExtraInputs;
|
|
732
795
|
kind: T['kind'];
|
|
733
|
-
name: string | undefined extends
|
|
796
|
+
name: string | undefined extends TName ? undefined : TName;
|
|
734
797
|
params: T['params'];
|
|
735
798
|
}>;
|
|
736
799
|
}
|
|
737
800
|
/**
|
|
738
|
-
*
|
|
739
|
-
*
|
|
801
|
+
* Creates a new extension blueprint that encapsulates the creation of
|
|
802
|
+
* extensions of particular kinds.
|
|
803
|
+
*
|
|
804
|
+
* @remarks
|
|
740
805
|
*
|
|
806
|
+
* For details on how blueprints work, see the
|
|
807
|
+
* {@link https://backstage.io/docs/frontend-system/architecture/extension-blueprints | documentation for extension blueprints}
|
|
808
|
+
* in the frontend system documentation.
|
|
809
|
+
*
|
|
810
|
+
* Extension blueprints make it much easier for users to create new extensions
|
|
811
|
+
* for your plugin. Rather than letting them use {@link createExtension}
|
|
812
|
+
* directly, you can define a set of parameters and default factory for your
|
|
813
|
+
* blueprint, removing a lot of the boilerplate and complexity that is otherwise
|
|
814
|
+
* needed to create an extension.
|
|
815
|
+
*
|
|
816
|
+
* Each blueprint has its own `kind` that helps identify and group the
|
|
817
|
+
* extensions that have been created with it. For example the
|
|
818
|
+
* {@link PageBlueprint} has the kind `'page'`, and extensions created with it
|
|
819
|
+
* will be given the ID `'page:<plugin-id>[/<name>]'`. Blueprints should always
|
|
820
|
+
* be exported as `<PascalCaseKind>Blueprint`.
|
|
821
|
+
*
|
|
822
|
+
* When creating a blueprint the type of the parameters are inferred from the
|
|
823
|
+
* `factory` function that you provide. The exception to that is when you need
|
|
824
|
+
* your blueprint to include inferred type parameters, in which case you need to
|
|
825
|
+
* use the `defineParams` option. See the documentation for the `defineParams`
|
|
826
|
+
* option for more details on how that works.
|
|
827
|
+
*
|
|
828
|
+
* @example
|
|
829
|
+
* ```tsx
|
|
830
|
+
* // In your plugin library
|
|
831
|
+
* export const GreetingBlueprint = createExtensionBlueprint({
|
|
832
|
+
* kind: 'greeting',
|
|
833
|
+
* attachTo: { id: 'example', input: 'greetings' },
|
|
834
|
+
* output: [coreExtensionData.reactElement],
|
|
835
|
+
* factory(params: { greeting: string }) {
|
|
836
|
+
* return [coreExtensionData.reactElement(<h1>{params.greeting}</h1>)];
|
|
837
|
+
* },
|
|
838
|
+
* });
|
|
839
|
+
*
|
|
840
|
+
* // Someone using your blueprint in their plugin
|
|
841
|
+
* const exampleGreeting = GreetingBlueprint.make({
|
|
842
|
+
* params: {
|
|
843
|
+
* greeting: 'Hello, world!',
|
|
844
|
+
* },
|
|
845
|
+
* });
|
|
846
|
+
* ```
|
|
741
847
|
* @public
|
|
742
848
|
*/
|
|
743
|
-
declare function createExtensionBlueprint<TParams extends object |
|
|
744
|
-
[inputName in string]: ExtensionInput<
|
|
849
|
+
declare function createExtensionBlueprint<TParams extends object | ExtensionBlueprintDefineParams, UOutput extends ExtensionDataRef, TInputs extends {
|
|
850
|
+
[inputName in string]: ExtensionInput<ExtensionDataRef, {
|
|
745
851
|
optional: boolean;
|
|
746
852
|
singleton: boolean;
|
|
747
853
|
}>;
|
|
748
854
|
}, TConfigSchema extends {
|
|
749
855
|
[key in string]: (zImpl: typeof z) => z.ZodType;
|
|
750
|
-
}, UFactoryOutput extends ExtensionDataValue<any, any>, TKind extends string,
|
|
751
|
-
[name in string]:
|
|
752
|
-
} = never>(options: CreateExtensionBlueprintOptions<TKind,
|
|
856
|
+
}, UFactoryOutput extends ExtensionDataValue<any, any>, TKind extends string, TDataRefs extends {
|
|
857
|
+
[name in string]: ExtensionDataRef;
|
|
858
|
+
} = never>(options: CreateExtensionBlueprintOptions<TKind, TParams, UOutput, TInputs, TConfigSchema, UFactoryOutput, TDataRefs>): ExtensionBlueprint<{
|
|
753
859
|
kind: TKind;
|
|
754
|
-
name: TName;
|
|
755
860
|
params: TParams;
|
|
756
|
-
output: UOutput;
|
|
861
|
+
output: UOutput extends ExtensionDataRef<infer IData, infer IId, infer IConfig> ? ExtensionDataRef<IData, IId, IConfig> : never;
|
|
757
862
|
inputs: string extends keyof TInputs ? {} : TInputs;
|
|
758
863
|
config: string extends keyof TConfigSchema ? {} : {
|
|
759
864
|
[key in keyof TConfigSchema]: z.infer<ReturnType<TConfigSchema[key]>>;
|
|
@@ -768,7 +873,7 @@ declare function createExtensionBlueprint<TParams extends object | ExtensionBlue
|
|
|
768
873
|
* Convert a single extension input into a matching resolved input.
|
|
769
874
|
* @public
|
|
770
875
|
*/
|
|
771
|
-
type ResolvedExtensionInput<TExtensionInput extends ExtensionInput<any, any>> = TExtensionInput['extensionData'] extends Array<
|
|
876
|
+
type ResolvedExtensionInput<TExtensionInput extends ExtensionInput<any, any>> = TExtensionInput['extensionData'] extends Array<ExtensionDataRef> ? {
|
|
772
877
|
node: AppNode;
|
|
773
878
|
} & ExtensionDataContainer<TExtensionInput['extensionData'][number]> : never;
|
|
774
879
|
/**
|
|
@@ -785,7 +890,7 @@ type PopUnion<U> = ToIntersection<U extends any ? () => U : never> extends () =>
|
|
|
785
890
|
/** @ignore */
|
|
786
891
|
type JoinStringUnion<U, TDiv extends string = ', ', TResult extends string = ''> = PopUnion<U> extends [infer IRest extends string, infer INext extends string] ? TResult extends '' ? JoinStringUnion<IRest, TDiv, INext> : JoinStringUnion<IRest, TDiv, `${TResult}${TDiv}${INext}`> : TResult;
|
|
787
892
|
/** @ignore */
|
|
788
|
-
type VerifyExtensionFactoryOutput<UDeclaredOutput extends
|
|
893
|
+
type VerifyExtensionFactoryOutput<UDeclaredOutput extends ExtensionDataRef, UFactoryOutput extends ExtensionDataValue<any, any>> = (UDeclaredOutput extends any ? UDeclaredOutput['config']['optional'] extends true ? never : UDeclaredOutput['id'] : never) extends infer IRequiredOutputIds ? [IRequiredOutputIds] extends [UFactoryOutput['id']] ? [UFactoryOutput['id']] extends [UDeclaredOutput['id']] ? {} : `Error: The extension factory has undeclared output(s): ${JoinStringUnion<Exclude<UFactoryOutput['id'], UDeclaredOutput['id']>>}` : `Error: The extension factory is missing the following output(s): ${JoinStringUnion<Exclude<IRequiredOutputIds, UFactoryOutput['id']>>}` : never;
|
|
789
894
|
/** @public */
|
|
790
895
|
type ExtensionAttachToSpec = {
|
|
791
896
|
id: string;
|
|
@@ -795,8 +900,8 @@ type ExtensionAttachToSpec = {
|
|
|
795
900
|
input: string;
|
|
796
901
|
}>;
|
|
797
902
|
/** @public */
|
|
798
|
-
type CreateExtensionOptions<TKind extends string | undefined, TName extends string | undefined, UOutput extends
|
|
799
|
-
[inputName in string]: ExtensionInput<
|
|
903
|
+
type CreateExtensionOptions<TKind extends string | undefined, TName extends string | undefined, UOutput extends ExtensionDataRef, TInputs extends {
|
|
904
|
+
[inputName in string]: ExtensionInput<ExtensionDataRef, {
|
|
800
905
|
optional: boolean;
|
|
801
906
|
singleton: boolean;
|
|
802
907
|
}>;
|
|
@@ -831,29 +936,29 @@ type ExtensionDefinitionParameters = {
|
|
|
831
936
|
config?: {
|
|
832
937
|
[K in string]: any;
|
|
833
938
|
};
|
|
834
|
-
output?:
|
|
939
|
+
output?: ExtensionDataRef;
|
|
835
940
|
inputs?: {
|
|
836
|
-
[KName in string]: ExtensionInput<
|
|
941
|
+
[KName in string]: ExtensionInput<ExtensionDataRef, {
|
|
837
942
|
optional: boolean;
|
|
838
943
|
singleton: boolean;
|
|
839
944
|
}>;
|
|
840
945
|
};
|
|
841
|
-
params?: object |
|
|
946
|
+
params?: object | ExtensionBlueprintDefineParams;
|
|
842
947
|
};
|
|
843
948
|
/**
|
|
844
949
|
* Same as the one in `createExtensionBlueprint`, but with `ParamsFactory` inlined.
|
|
845
950
|
* It can't be exported because it breaks API reports.
|
|
846
951
|
* @ignore
|
|
847
952
|
*/
|
|
848
|
-
type AnyParamsInput<TParams extends object |
|
|
953
|
+
type AnyParamsInput<TParams extends object | ExtensionBlueprintDefineParams> = TParams extends ExtensionBlueprintDefineParams<infer IParams> ? IParams | ((define: TParams) => ReturnType<TParams>) : TParams | ((define: ExtensionBlueprintDefineParams<TParams, TParams>) => ReturnType<ExtensionBlueprintDefineParams<TParams, TParams>>);
|
|
849
954
|
/** @public */
|
|
850
955
|
type ExtensionDefinition<T extends ExtensionDefinitionParameters = ExtensionDefinitionParameters> = {
|
|
851
956
|
$$type: '@backstage/ExtensionDefinition';
|
|
852
957
|
readonly T: T;
|
|
853
958
|
override<TExtensionConfigSchema extends {
|
|
854
959
|
[key in string]: (zImpl: typeof z) => z.ZodType;
|
|
855
|
-
}, UFactoryOutput extends ExtensionDataValue<any, any>, UNewOutput extends
|
|
856
|
-
[inputName in string]: ExtensionInput<
|
|
960
|
+
}, UFactoryOutput extends ExtensionDataValue<any, any>, UNewOutput extends ExtensionDataRef, TExtraInputs extends {
|
|
961
|
+
[inputName in string]: ExtensionInput<ExtensionDataRef, {
|
|
857
962
|
optional: boolean;
|
|
858
963
|
singleton: boolean;
|
|
859
964
|
}>;
|
|
@@ -871,9 +976,9 @@ type ExtensionDefinition<T extends ExtensionDefinitionParameters = ExtensionDefi
|
|
|
871
976
|
};
|
|
872
977
|
factory?(originalFactory: <TFactoryParamsReturn extends AnyParamsInput<NonNullable<T['params']>>>(context?: Expand<{
|
|
873
978
|
config?: T['config'];
|
|
874
|
-
inputs?:
|
|
979
|
+
inputs?: ResolvedInputValueOverrides<NonNullable<T['inputs']>>;
|
|
875
980
|
} & ([T['params']] extends [never] ? {} : {
|
|
876
|
-
params?: TFactoryParamsReturn extends
|
|
981
|
+
params?: TFactoryParamsReturn extends ExtensionBlueprintDefineParams ? TFactoryParamsReturn : T['params'] extends ExtensionBlueprintDefineParams ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `originalFactory(defineParams => defineParams(<params>))`' : Partial<T['params']>;
|
|
877
982
|
})>) => ExtensionDataContainer<NonNullable<T['output']>>, context: {
|
|
878
983
|
node: AppNode;
|
|
879
984
|
apis: ApiHolder;
|
|
@@ -883,11 +988,11 @@ type ExtensionDefinition<T extends ExtensionDefinitionParameters = ExtensionDefi
|
|
|
883
988
|
inputs: Expand<ResolvedExtensionInputs<T['inputs'] & TExtraInputs>>;
|
|
884
989
|
}): Iterable<UFactoryOutput>;
|
|
885
990
|
} & ([T['params']] extends [never] ? {} : {
|
|
886
|
-
params?: TParamsInput extends
|
|
887
|
-
})> & VerifyExtensionFactoryOutput<
|
|
991
|
+
params?: TParamsInput extends ExtensionBlueprintDefineParams ? TParamsInput : T['params'] extends ExtensionBlueprintDefineParams ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `originalFactory(defineParams => defineParams(<params>))`' : Partial<T['params']>;
|
|
992
|
+
})> & VerifyExtensionFactoryOutput<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UFactoryOutput>): ExtensionDefinition<{
|
|
888
993
|
kind: T['kind'];
|
|
889
994
|
name: T['name'];
|
|
890
|
-
output:
|
|
995
|
+
output: ExtensionDataRef extends UNewOutput ? T['output'] : UNewOutput;
|
|
891
996
|
inputs: T['inputs'] & TExtraInputs;
|
|
892
997
|
config: T['config'] & {
|
|
893
998
|
[key in keyof TExtensionConfigSchema]: z.infer<ReturnType<TExtensionConfigSchema[key]>>;
|
|
@@ -897,9 +1002,43 @@ type ExtensionDefinition<T extends ExtensionDefinitionParameters = ExtensionDefi
|
|
|
897
1002
|
}>>;
|
|
898
1003
|
}>;
|
|
899
1004
|
};
|
|
900
|
-
/**
|
|
901
|
-
|
|
902
|
-
|
|
1005
|
+
/**
|
|
1006
|
+
* Creates a new extension definition for installation in a Backstage app.
|
|
1007
|
+
*
|
|
1008
|
+
* @remarks
|
|
1009
|
+
*
|
|
1010
|
+
* This is a low-level function for creation of extensions with arbitrary inputs
|
|
1011
|
+
* and outputs and is typically only intended to be used for advanced overrides
|
|
1012
|
+
* or framework-level extensions. For most extension creation needs, it is
|
|
1013
|
+
* recommended to use existing {@link ExtensionBlueprint}s instead. You can find
|
|
1014
|
+
* blueprints both in the `@backstage/frontend-plugin-api` package as well as
|
|
1015
|
+
* other plugin libraries. There is also a list of
|
|
1016
|
+
* {@link https://backstage.io/docs/frontend-system/building-plugins/common-extension-blueprints | commonly used blueprints}
|
|
1017
|
+
* in the frontend system documentation.
|
|
1018
|
+
*
|
|
1019
|
+
* Extension definitions that are created with this function can be installed in
|
|
1020
|
+
* a Backstage app via a {@link FrontendPlugin} or {@link FrontendModule}.
|
|
1021
|
+
*
|
|
1022
|
+
* For more details on how extensions work, see the
|
|
1023
|
+
* {@link https://backstage.io/docs/frontend-system/architecture/extensions | documentation for extensions}.
|
|
1024
|
+
*
|
|
1025
|
+
* @example
|
|
1026
|
+
*
|
|
1027
|
+
* ```ts
|
|
1028
|
+
* const myExtension = createExtension({
|
|
1029
|
+
* name: 'example',
|
|
1030
|
+
* attachTo: { id: 'app', input: 'root' },
|
|
1031
|
+
* output: [coreExtensionData.reactElement],
|
|
1032
|
+
* factory() {
|
|
1033
|
+
* return [coreExtensionData.reactElement(<h1>Hello, world!</h1>)];
|
|
1034
|
+
* },
|
|
1035
|
+
* });
|
|
1036
|
+
* ```
|
|
1037
|
+
*
|
|
1038
|
+
* @public
|
|
1039
|
+
*/
|
|
1040
|
+
declare function createExtension<UOutput extends ExtensionDataRef, TInputs extends {
|
|
1041
|
+
[inputName in string]: ExtensionInput<ExtensionDataRef, {
|
|
903
1042
|
optional: boolean;
|
|
904
1043
|
singleton: boolean;
|
|
905
1044
|
}>;
|
|
@@ -912,7 +1051,7 @@ declare function createExtension<UOutput extends AnyExtensionDataRef, TInputs ex
|
|
|
912
1051
|
configInput: string extends keyof TConfigSchema ? {} : z.input<z.ZodObject<{
|
|
913
1052
|
[key in keyof TConfigSchema]: ReturnType<TConfigSchema[key]>;
|
|
914
1053
|
}>>;
|
|
915
|
-
output: UOutput;
|
|
1054
|
+
output: UOutput extends ExtensionDataRef<infer IData, infer IId, infer IConfig> ? ExtensionDataRef<IData, IId, IConfig> : never;
|
|
916
1055
|
inputs: TInputs;
|
|
917
1056
|
params: never;
|
|
918
1057
|
kind: string | undefined extends TKind ? undefined : TKind;
|
|
@@ -953,11 +1092,7 @@ interface AppNodeSpec {
|
|
|
953
1092
|
readonly extension: Extension<unknown, unknown>;
|
|
954
1093
|
readonly disabled: boolean;
|
|
955
1094
|
readonly config?: unknown;
|
|
956
|
-
readonly plugin
|
|
957
|
-
/**
|
|
958
|
-
* @deprecated Use {@link AppNodeSpec.plugin} instead.
|
|
959
|
-
*/
|
|
960
|
-
readonly source?: FrontendPlugin;
|
|
1095
|
+
readonly plugin: FrontendPlugin;
|
|
961
1096
|
}
|
|
962
1097
|
/**
|
|
963
1098
|
* The connections from this {@link AppNode} to other nodes.
|
|
@@ -1032,7 +1167,7 @@ interface AppTreeApi {
|
|
|
1032
1167
|
/**
|
|
1033
1168
|
* Get all nodes in the app that are mounted at a given route path.
|
|
1034
1169
|
*/
|
|
1035
|
-
getNodesByRoutePath(
|
|
1170
|
+
getNodesByRoutePath(routePath: string): {
|
|
1036
1171
|
nodes: AppNode[];
|
|
1037
1172
|
};
|
|
1038
1173
|
}
|
|
@@ -1046,12 +1181,6 @@ declare const appTreeApiRef: _backstage_core_plugin_api.ApiRef<AppTreeApi>;
|
|
|
1046
1181
|
/** @public */
|
|
1047
1182
|
interface ExtensionBoundaryProps {
|
|
1048
1183
|
node: AppNode;
|
|
1049
|
-
/**
|
|
1050
|
-
* This explicitly marks the extension as routable for the purpose of
|
|
1051
|
-
* capturing analytics events. If not provided, the extension boundary will be
|
|
1052
|
-
* marked as routable if it outputs a routePath.
|
|
1053
|
-
*/
|
|
1054
|
-
routable?: boolean;
|
|
1055
1184
|
children: ReactNode;
|
|
1056
1185
|
}
|
|
1057
1186
|
/** @public */
|
|
@@ -1063,33 +1192,30 @@ declare namespace ExtensionBoundary {
|
|
|
1063
1192
|
}
|
|
1064
1193
|
|
|
1065
1194
|
/** @public */
|
|
1066
|
-
type
|
|
1195
|
+
type SwappableComponentRef<TInnerComponentProps extends {} = {}, TExternalComponentProps extends {} = TInnerComponentProps> = {
|
|
1067
1196
|
id: string;
|
|
1068
|
-
|
|
1197
|
+
TProps: TInnerComponentProps;
|
|
1198
|
+
TExternalProps: TExternalComponentProps;
|
|
1199
|
+
$$type: '@backstage/SwappableComponentRef';
|
|
1069
1200
|
};
|
|
1070
|
-
/**
|
|
1071
|
-
|
|
1201
|
+
/**
|
|
1202
|
+
* Options for creating an SwappableComponent.
|
|
1203
|
+
*
|
|
1204
|
+
* @public
|
|
1205
|
+
*/
|
|
1206
|
+
type CreateSwappableComponentOptions<TInnerComponentProps extends {}, TExternalComponentProps extends {} = TInnerComponentProps> = {
|
|
1072
1207
|
id: string;
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
/** @public */
|
|
1076
|
-
type CoreProgressProps = {};
|
|
1077
|
-
/** @public */
|
|
1078
|
-
type CoreNotFoundErrorPageProps = {
|
|
1079
|
-
children?: ReactNode;
|
|
1080
|
-
};
|
|
1081
|
-
/** @public */
|
|
1082
|
-
type CoreErrorBoundaryFallbackProps = {
|
|
1083
|
-
plugin?: FrontendPlugin;
|
|
1084
|
-
error: Error;
|
|
1085
|
-
resetError: () => void;
|
|
1208
|
+
loader?: (() => (props: TInnerComponentProps) => JSX.Element | null) | (() => Promise<(props: TInnerComponentProps) => JSX.Element | null>);
|
|
1209
|
+
transformProps?: (props: TExternalComponentProps) => TInnerComponentProps;
|
|
1086
1210
|
};
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1211
|
+
/**
|
|
1212
|
+
* Creates a SwappableComponent that can be used to render the component, optionally overridden by the app.
|
|
1213
|
+
*
|
|
1214
|
+
* @public
|
|
1215
|
+
*/
|
|
1216
|
+
declare function createSwappableComponent<TInnerComponentProps extends {}, TExternalComponentProps extends {} = TInnerComponentProps>(options: CreateSwappableComponentOptions<TInnerComponentProps, TExternalComponentProps>): {
|
|
1217
|
+
(props: TExternalComponentProps): JSX.Element | null;
|
|
1218
|
+
ref: SwappableComponentRef<TInnerComponentProps, TExternalComponentProps>;
|
|
1093
1219
|
};
|
|
1094
1220
|
|
|
1095
1221
|
/**
|
|
@@ -1107,25 +1233,55 @@ declare const coreComponentRefs: {
|
|
|
1107
1233
|
*/
|
|
1108
1234
|
declare function useAppNode(): AppNode | undefined;
|
|
1109
1235
|
|
|
1236
|
+
/** @public */
|
|
1237
|
+
type ProgressProps = {};
|
|
1238
|
+
/** @public */
|
|
1239
|
+
type NotFoundErrorPageProps = {
|
|
1240
|
+
children?: ReactNode;
|
|
1241
|
+
};
|
|
1242
|
+
/** @public */
|
|
1243
|
+
type ErrorDisplayProps = {
|
|
1244
|
+
plugin?: FrontendPlugin;
|
|
1245
|
+
error: Error;
|
|
1246
|
+
resetError: () => void;
|
|
1247
|
+
};
|
|
1248
|
+
|
|
1110
1249
|
/**
|
|
1111
|
-
* API for looking up components based on component refs.
|
|
1112
|
-
*
|
|
1113
1250
|
* @public
|
|
1114
1251
|
*/
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1252
|
+
declare const Progress: {
|
|
1253
|
+
(props: ProgressProps): JSX.Element | null;
|
|
1254
|
+
ref: SwappableComponentRef<ProgressProps, ProgressProps>;
|
|
1255
|
+
};
|
|
1256
|
+
/**
|
|
1257
|
+
* @public
|
|
1258
|
+
*/
|
|
1259
|
+
declare const NotFoundErrorPage: {
|
|
1260
|
+
(props: NotFoundErrorPageProps): JSX.Element | null;
|
|
1261
|
+
ref: SwappableComponentRef<NotFoundErrorPageProps, NotFoundErrorPageProps>;
|
|
1262
|
+
};
|
|
1118
1263
|
/**
|
|
1119
|
-
*
|
|
1264
|
+
* @public
|
|
1265
|
+
*/
|
|
1266
|
+
declare const ErrorDisplay: {
|
|
1267
|
+
(props: ErrorDisplayProps): JSX.Element | null;
|
|
1268
|
+
ref: SwappableComponentRef<ErrorDisplayProps, ErrorDisplayProps>;
|
|
1269
|
+
};
|
|
1270
|
+
|
|
1271
|
+
/**
|
|
1272
|
+
* API for looking up components based on component refs.
|
|
1120
1273
|
*
|
|
1121
1274
|
* @public
|
|
1122
1275
|
*/
|
|
1123
|
-
|
|
1276
|
+
interface SwappableComponentsApi {
|
|
1277
|
+
getComponent<TInnerComponentProps extends {}, TExternalComponentProps extends {} = TInnerComponentProps>(ref: SwappableComponentRef<TInnerComponentProps, TExternalComponentProps>): (props: TInnerComponentProps) => JSX.Element | null;
|
|
1278
|
+
}
|
|
1124
1279
|
/**
|
|
1280
|
+
* The `ApiRef` of {@link SwappableComponentsApi}.
|
|
1281
|
+
*
|
|
1125
1282
|
* @public
|
|
1126
|
-
* Returns the component associated with the given ref.
|
|
1127
1283
|
*/
|
|
1128
|
-
declare
|
|
1284
|
+
declare const swappableComponentsApiRef: _backstage_core_plugin_api.ApiRef<SwappableComponentsApi>;
|
|
1129
1285
|
|
|
1130
1286
|
/**
|
|
1131
1287
|
* IconComponent is the common icon type used throughout Backstage when
|
|
@@ -1172,7 +1328,7 @@ declare const iconsApiRef: _backstage_core_plugin_api.ApiRef<IconsApi>;
|
|
|
1172
1328
|
*
|
|
1173
1329
|
* @public
|
|
1174
1330
|
*/
|
|
1175
|
-
interface DialogApiDialog<TResult =
|
|
1331
|
+
interface DialogApiDialog<TResult = void> {
|
|
1176
1332
|
/**
|
|
1177
1333
|
* Closes the dialog with that provided result.
|
|
1178
1334
|
*
|
|
@@ -1249,7 +1405,7 @@ interface DialogApi {
|
|
|
1249
1405
|
* @param elementOrComponent - The element or component to render in the dialog. If a component is provided, it will be provided with a `dialog` prop that contains the dialog handle.
|
|
1250
1406
|
* @public
|
|
1251
1407
|
*/
|
|
1252
|
-
show<TResult =
|
|
1408
|
+
show<TResult = void>(elementOrComponent: JSX.Element | ((props: {
|
|
1253
1409
|
dialog: DialogApiDialog<TResult | undefined>;
|
|
1254
1410
|
}) => JSX.Element)): DialogApiDialog<TResult | undefined>;
|
|
1255
1411
|
/**
|
|
@@ -1296,7 +1452,7 @@ interface DialogApi {
|
|
|
1296
1452
|
* @param elementOrComponent - The element or component to render in the dialog. If a component is provided, it will be provided with a `dialog` prop that contains the dialog handle.
|
|
1297
1453
|
* @public
|
|
1298
1454
|
*/
|
|
1299
|
-
showModal<TResult =
|
|
1455
|
+
showModal<TResult = void>(elementOrComponent: JSX.Element | ((props: {
|
|
1300
1456
|
dialog: DialogApiDialog<TResult>;
|
|
1301
1457
|
}) => JSX.Element)): DialogApiDialog<TResult>;
|
|
1302
1458
|
}
|
|
@@ -1321,21 +1477,17 @@ declare const dialogApiRef: _backstage_core_plugin_api.ApiRef<DialogApi>;
|
|
|
1321
1477
|
* @public
|
|
1322
1478
|
*/
|
|
1323
1479
|
type RouteFunc<TParams extends AnyRouteRefParams> = (...[params]: TParams extends undefined ? readonly [] : readonly [params: TParams]) => string;
|
|
1324
|
-
/**
|
|
1325
|
-
* @public
|
|
1326
|
-
*/
|
|
1327
|
-
type RouteResolutionApiResolveOptions = {
|
|
1328
|
-
/**
|
|
1329
|
-
* An absolute path to use as a starting point when resolving the route.
|
|
1330
|
-
* If no path is provided the route will be resolved from the root of the app.
|
|
1331
|
-
*/
|
|
1332
|
-
sourcePath?: string;
|
|
1333
|
-
};
|
|
1334
1480
|
/**
|
|
1335
1481
|
* @public
|
|
1336
1482
|
*/
|
|
1337
1483
|
interface RouteResolutionApi {
|
|
1338
|
-
resolve<TParams extends AnyRouteRefParams>(anyRouteRef: RouteRef<TParams> | SubRouteRef<TParams> | ExternalRouteRef<TParams>, options?:
|
|
1484
|
+
resolve<TParams extends AnyRouteRefParams>(anyRouteRef: RouteRef<TParams> | SubRouteRef<TParams> | ExternalRouteRef<TParams>, options?: {
|
|
1485
|
+
/**
|
|
1486
|
+
* An absolute path to use as a starting point when resolving the route.
|
|
1487
|
+
* If no path is provided the route will be resolved from the root of the app.
|
|
1488
|
+
*/
|
|
1489
|
+
sourcePath?: string;
|
|
1490
|
+
}): RouteFunc<TParams> | undefined;
|
|
1339
1491
|
}
|
|
1340
1492
|
/**
|
|
1341
1493
|
* The `ApiRef` of {@link RouteResolutionApi}.
|
|
@@ -1418,6 +1570,25 @@ type AnalyticsTracker = {
|
|
|
1418
1570
|
attributes?: AnalyticsEventAttributes;
|
|
1419
1571
|
}) => void;
|
|
1420
1572
|
};
|
|
1573
|
+
/**
|
|
1574
|
+
* Analytics implementations are used to track user behavior in a Backstage
|
|
1575
|
+
* instance.
|
|
1576
|
+
*
|
|
1577
|
+
* @remarks
|
|
1578
|
+
*
|
|
1579
|
+
* To instrument your App or Plugin, retrieve an analytics tracker using the
|
|
1580
|
+
* `useAnalytics()` hook. This will return a pre-configured `AnalyticsTracker`
|
|
1581
|
+
* with relevant methods for instrumentation.
|
|
1582
|
+
*
|
|
1583
|
+
* @public
|
|
1584
|
+
*/
|
|
1585
|
+
type AnalyticsImplementation = {
|
|
1586
|
+
/**
|
|
1587
|
+
* Primary event handler responsible for compiling and forwarding events to
|
|
1588
|
+
* an analytics system.
|
|
1589
|
+
*/
|
|
1590
|
+
captureEvent(event: AnalyticsEvent): void;
|
|
1591
|
+
};
|
|
1421
1592
|
/**
|
|
1422
1593
|
* The Analytics API is used to track user behavior in a Backstage instance.
|
|
1423
1594
|
*
|
|
@@ -1439,6 +1610,11 @@ type AnalyticsApi = {
|
|
|
1439
1610
|
/**
|
|
1440
1611
|
* The API reference of {@link AnalyticsApi}.
|
|
1441
1612
|
*
|
|
1613
|
+
* @remarks
|
|
1614
|
+
*
|
|
1615
|
+
* To define a concrete Analytics Implementation, use
|
|
1616
|
+
* {@link AnalyticsImplementationBlueprint} instead.
|
|
1617
|
+
*
|
|
1442
1618
|
* @public
|
|
1443
1619
|
*/
|
|
1444
1620
|
declare const analyticsApiRef: ApiRef<AnalyticsApi>;
|
|
@@ -1450,6 +1626,30 @@ declare const analyticsApiRef: ApiRef<AnalyticsApi>;
|
|
|
1450
1626
|
*/
|
|
1451
1627
|
declare function useAnalytics(): AnalyticsTracker;
|
|
1452
1628
|
|
|
1629
|
+
/** @public */
|
|
1630
|
+
type AnalyticsImplementationFactory<Deps extends {
|
|
1631
|
+
[name in string]: unknown;
|
|
1632
|
+
} = {}> = {
|
|
1633
|
+
deps: TypesToApiRefs<Deps>;
|
|
1634
|
+
factory(deps: Deps): AnalyticsImplementation;
|
|
1635
|
+
};
|
|
1636
|
+
/**
|
|
1637
|
+
* Creates analytics implementations.
|
|
1638
|
+
*
|
|
1639
|
+
* @public
|
|
1640
|
+
*/
|
|
1641
|
+
declare const AnalyticsImplementationBlueprint: ExtensionBlueprint<{
|
|
1642
|
+
kind: "analytics";
|
|
1643
|
+
params: <TDeps extends { [name in string]: unknown; }>(params: AnalyticsImplementationFactory<TDeps>) => ExtensionBlueprintParams<AnalyticsImplementationFactory<{}>>;
|
|
1644
|
+
output: ExtensionDataRef<AnalyticsImplementationFactory<{}>, "core.analytics.factory", {}>;
|
|
1645
|
+
inputs: {};
|
|
1646
|
+
config: {};
|
|
1647
|
+
configInput: {};
|
|
1648
|
+
dataRefs: {
|
|
1649
|
+
factory: ConfigurableExtensionDataRef<AnalyticsImplementationFactory<{}>, "core.analytics.factory", {}>;
|
|
1650
|
+
};
|
|
1651
|
+
}>;
|
|
1652
|
+
|
|
1453
1653
|
/**
|
|
1454
1654
|
* Creates utility API extensions.
|
|
1455
1655
|
*
|
|
@@ -1457,9 +1657,8 @@ declare function useAnalytics(): AnalyticsTracker;
|
|
|
1457
1657
|
*/
|
|
1458
1658
|
declare const ApiBlueprint: ExtensionBlueprint<{
|
|
1459
1659
|
kind: "api";
|
|
1460
|
-
name: undefined;
|
|
1461
1660
|
params: <TApi, TImpl extends TApi, TDeps extends { [name in string]: unknown; }>(params: ApiFactory<TApi, TImpl, TDeps>) => ExtensionBlueprintParams<AnyApiFactory>;
|
|
1462
|
-
output:
|
|
1661
|
+
output: ExtensionDataRef<AnyApiFactory, "core.api.factory", {}>;
|
|
1463
1662
|
inputs: {};
|
|
1464
1663
|
config: {};
|
|
1465
1664
|
configInput: {};
|
|
@@ -1476,11 +1675,10 @@ declare const ApiBlueprint: ExtensionBlueprint<{
|
|
|
1476
1675
|
*/
|
|
1477
1676
|
declare const AppRootElementBlueprint: ExtensionBlueprint<{
|
|
1478
1677
|
kind: "app-root-element";
|
|
1479
|
-
name: undefined;
|
|
1480
1678
|
params: {
|
|
1481
|
-
element: JSX.Element
|
|
1679
|
+
element: JSX.Element;
|
|
1482
1680
|
};
|
|
1483
|
-
output:
|
|
1681
|
+
output: ExtensionDataRef<react.JSX.Element, "core.reactElement", {}>;
|
|
1484
1682
|
inputs: {};
|
|
1485
1683
|
config: {};
|
|
1486
1684
|
configInput: {};
|
|
@@ -1496,31 +1694,33 @@ declare const AppRootElementBlueprint: ExtensionBlueprint<{
|
|
|
1496
1694
|
*/
|
|
1497
1695
|
declare const AppRootWrapperBlueprint: ExtensionBlueprint<{
|
|
1498
1696
|
kind: "app-root-wrapper";
|
|
1499
|
-
name: undefined;
|
|
1500
1697
|
params: {
|
|
1501
|
-
|
|
1698
|
+
/** @deprecated use the `component` parameter instead */
|
|
1699
|
+
Component?: [error: "Use the `component` parameter instead"];
|
|
1700
|
+
component: (props: {
|
|
1701
|
+
children: ReactNode;
|
|
1702
|
+
}) => JSX.Element | null;
|
|
1502
1703
|
};
|
|
1503
|
-
output:
|
|
1504
|
-
children
|
|
1505
|
-
}
|
|
1704
|
+
output: ExtensionDataRef<(props: {
|
|
1705
|
+
children: ReactNode;
|
|
1706
|
+
}) => JSX.Element | null, "app.root.wrapper", {}>;
|
|
1506
1707
|
inputs: {};
|
|
1507
1708
|
config: {};
|
|
1508
1709
|
configInput: {};
|
|
1509
1710
|
dataRefs: {
|
|
1510
|
-
component: ConfigurableExtensionDataRef<
|
|
1511
|
-
children
|
|
1512
|
-
}
|
|
1711
|
+
component: ConfigurableExtensionDataRef<(props: {
|
|
1712
|
+
children: ReactNode;
|
|
1713
|
+
}) => JSX.Element | null, "app.root.wrapper", {}>;
|
|
1513
1714
|
};
|
|
1514
1715
|
}>;
|
|
1515
1716
|
|
|
1516
1717
|
/** @public */
|
|
1517
1718
|
declare const IconBundleBlueprint: ExtensionBlueprint<{
|
|
1518
1719
|
kind: "icon-bundle";
|
|
1519
|
-
name: undefined;
|
|
1520
1720
|
params: {
|
|
1521
1721
|
icons: { [key in string]: IconComponent; };
|
|
1522
1722
|
};
|
|
1523
|
-
output:
|
|
1723
|
+
output: ExtensionDataRef<{
|
|
1524
1724
|
[x: string]: IconComponent;
|
|
1525
1725
|
}, "core.icons", {}>;
|
|
1526
1726
|
inputs: {};
|
|
@@ -1568,11 +1768,10 @@ type NavContentComponent = (props: NavContentComponentProps) => JSX.Element | nu
|
|
|
1568
1768
|
*/
|
|
1569
1769
|
declare const NavContentBlueprint: _backstage_frontend_plugin_api.ExtensionBlueprint<{
|
|
1570
1770
|
kind: "nav-content";
|
|
1571
|
-
name: undefined;
|
|
1572
1771
|
params: {
|
|
1573
1772
|
component: NavContentComponent;
|
|
1574
1773
|
};
|
|
1575
|
-
output: _backstage_frontend_plugin_api.
|
|
1774
|
+
output: _backstage_frontend_plugin_api.ExtensionDataRef<NavContentComponent, "core.nav-content.component", {}>;
|
|
1576
1775
|
inputs: {};
|
|
1577
1776
|
config: {};
|
|
1578
1777
|
configInput: {};
|
|
@@ -1588,13 +1787,12 @@ declare const NavContentBlueprint: _backstage_frontend_plugin_api.ExtensionBluep
|
|
|
1588
1787
|
*/
|
|
1589
1788
|
declare const NavItemBlueprint: ExtensionBlueprint<{
|
|
1590
1789
|
kind: "nav-item";
|
|
1591
|
-
name: undefined;
|
|
1592
1790
|
params: {
|
|
1593
1791
|
title: string;
|
|
1594
1792
|
icon: IconComponent$2;
|
|
1595
1793
|
routeRef: RouteRef<undefined>;
|
|
1596
1794
|
};
|
|
1597
|
-
output:
|
|
1795
|
+
output: ExtensionDataRef<{
|
|
1598
1796
|
title: string;
|
|
1599
1797
|
icon: IconComponent$2;
|
|
1600
1798
|
routeRef: RouteRef<undefined>;
|
|
@@ -1618,13 +1816,16 @@ declare const NavItemBlueprint: ExtensionBlueprint<{
|
|
|
1618
1816
|
*/
|
|
1619
1817
|
declare const PageBlueprint: ExtensionBlueprint<{
|
|
1620
1818
|
kind: "page";
|
|
1621
|
-
name: undefined;
|
|
1622
1819
|
params: {
|
|
1623
|
-
|
|
1820
|
+
/**
|
|
1821
|
+
* @deprecated Use the `path` param instead.
|
|
1822
|
+
*/
|
|
1823
|
+
defaultPath?: [Error: `Use the 'path' param instead`];
|
|
1824
|
+
path: string;
|
|
1624
1825
|
loader: () => Promise<JSX.Element>;
|
|
1625
1826
|
routeRef?: RouteRef;
|
|
1626
1827
|
};
|
|
1627
|
-
output:
|
|
1828
|
+
output: ExtensionDataRef<string, "core.routing.path", {}> | ExtensionDataRef<react.JSX.Element, "core.reactElement", {}> | ExtensionDataRef<RouteRef<AnyRouteRefParams>, "core.routing.ref", {
|
|
1628
1829
|
optional: true;
|
|
1629
1830
|
}>;
|
|
1630
1831
|
inputs: {};
|
|
@@ -1640,20 +1841,23 @@ declare const PageBlueprint: ExtensionBlueprint<{
|
|
|
1640
1841
|
/** @public */
|
|
1641
1842
|
declare const RouterBlueprint: ExtensionBlueprint<{
|
|
1642
1843
|
kind: "app-router-component";
|
|
1643
|
-
name: undefined;
|
|
1644
1844
|
params: {
|
|
1645
|
-
|
|
1845
|
+
/** @deprecated use the `component` parameter instead */
|
|
1846
|
+
Component?: [error: "Use the `component` parameter instead"];
|
|
1847
|
+
component: (props: {
|
|
1848
|
+
children: ReactNode;
|
|
1849
|
+
}) => JSX.Element | null;
|
|
1646
1850
|
};
|
|
1647
|
-
output:
|
|
1648
|
-
children
|
|
1649
|
-
}
|
|
1851
|
+
output: ExtensionDataRef<(props: {
|
|
1852
|
+
children: ReactNode;
|
|
1853
|
+
}) => JSX.Element | null, "app.router.wrapper", {}>;
|
|
1650
1854
|
inputs: {};
|
|
1651
1855
|
config: {};
|
|
1652
1856
|
configInput: {};
|
|
1653
1857
|
dataRefs: {
|
|
1654
|
-
component: ConfigurableExtensionDataRef<
|
|
1655
|
-
children
|
|
1656
|
-
}
|
|
1858
|
+
component: ConfigurableExtensionDataRef<(props: {
|
|
1859
|
+
children: ReactNode;
|
|
1860
|
+
}) => JSX.Element | null, "app.router.wrapper", {}>;
|
|
1657
1861
|
};
|
|
1658
1862
|
}>;
|
|
1659
1863
|
|
|
@@ -1664,11 +1868,10 @@ declare const RouterBlueprint: ExtensionBlueprint<{
|
|
|
1664
1868
|
*/
|
|
1665
1869
|
declare const SignInPageBlueprint: ExtensionBlueprint<{
|
|
1666
1870
|
kind: "sign-in-page";
|
|
1667
|
-
name: undefined;
|
|
1668
1871
|
params: {
|
|
1669
1872
|
loader: () => Promise<ComponentType<SignInPageProps>>;
|
|
1670
1873
|
};
|
|
1671
|
-
output:
|
|
1874
|
+
output: ExtensionDataRef<ComponentType<SignInPageProps>, "core.sign-in-page.component", {}>;
|
|
1672
1875
|
inputs: {};
|
|
1673
1876
|
config: {};
|
|
1674
1877
|
configInput: {};
|
|
@@ -1684,11 +1887,10 @@ declare const SignInPageBlueprint: ExtensionBlueprint<{
|
|
|
1684
1887
|
*/
|
|
1685
1888
|
declare const ThemeBlueprint: ExtensionBlueprint<{
|
|
1686
1889
|
kind: "theme";
|
|
1687
|
-
name: undefined;
|
|
1688
1890
|
params: {
|
|
1689
1891
|
theme: AppTheme;
|
|
1690
1892
|
};
|
|
1691
|
-
output:
|
|
1893
|
+
output: ExtensionDataRef<AppTheme, "core.theme.theme", {}>;
|
|
1692
1894
|
inputs: {};
|
|
1693
1895
|
config: {};
|
|
1694
1896
|
configInput: {};
|
|
@@ -1704,11 +1906,10 @@ declare const ThemeBlueprint: ExtensionBlueprint<{
|
|
|
1704
1906
|
*/
|
|
1705
1907
|
declare const TranslationBlueprint: ExtensionBlueprint<{
|
|
1706
1908
|
kind: "translation";
|
|
1707
|
-
name: undefined;
|
|
1708
1909
|
params: {
|
|
1709
1910
|
resource: TranslationResource | TranslationMessages;
|
|
1710
1911
|
};
|
|
1711
|
-
output:
|
|
1912
|
+
output: ExtensionDataRef<TranslationResource<string> | TranslationMessages<string, {
|
|
1712
1913
|
[x: string]: string;
|
|
1713
1914
|
}, boolean>, "core.translation.translation", {}>;
|
|
1714
1915
|
inputs: {};
|
|
@@ -1721,39 +1922,37 @@ declare const TranslationBlueprint: ExtensionBlueprint<{
|
|
|
1721
1922
|
};
|
|
1722
1923
|
}>;
|
|
1723
1924
|
|
|
1724
|
-
/**
|
|
1725
|
-
|
|
1726
|
-
|
|
1727
|
-
|
|
1728
|
-
|
|
1729
|
-
|
|
1730
|
-
|
|
1731
|
-
|
|
1732
|
-
|
|
1733
|
-
|
|
1734
|
-
}):
|
|
1925
|
+
/**
|
|
1926
|
+
* Blueprint for creating swappable components from a SwappableComponentRef and a loader
|
|
1927
|
+
*
|
|
1928
|
+
* @public
|
|
1929
|
+
*/
|
|
1930
|
+
declare const SwappableComponentBlueprint: ExtensionBlueprint<{
|
|
1931
|
+
kind: "component";
|
|
1932
|
+
params: <Ref extends SwappableComponentRef<any>>(params: {
|
|
1933
|
+
component: Ref extends SwappableComponentRef<any, infer IExternalComponentProps> ? {
|
|
1934
|
+
ref: Ref;
|
|
1935
|
+
} & ((props: IExternalComponentProps) => JSX.Element | null) : never;
|
|
1936
|
+
loader: Ref extends SwappableComponentRef<infer IInnerComponentProps, any> ? (() => (props: IInnerComponentProps) => JSX.Element | null) | (() => Promise<(props: IInnerComponentProps) => JSX.Element | null>) : never;
|
|
1937
|
+
}) => ExtensionBlueprintParams<{
|
|
1938
|
+
component: Ref extends SwappableComponentRef<any, infer IExternalComponentProps> ? {
|
|
1939
|
+
ref: Ref;
|
|
1940
|
+
} & ((props: IExternalComponentProps) => JSX.Element | null) : never;
|
|
1941
|
+
loader: Ref extends SwappableComponentRef<infer IInnerComponentProps, any> ? (() => (props: IInnerComponentProps) => JSX.Element | null) | (() => Promise<(props: IInnerComponentProps) => JSX.Element | null>) : never;
|
|
1942
|
+
}>;
|
|
1943
|
+
output: ExtensionDataRef<{
|
|
1944
|
+
ref: SwappableComponentRef;
|
|
1945
|
+
loader: (() => (props: {}) => JSX.Element | null) | (() => Promise<(props: {}) => JSX.Element | null>);
|
|
1946
|
+
}, "core.swappableComponent", {}>;
|
|
1947
|
+
inputs: {};
|
|
1735
1948
|
config: {};
|
|
1736
1949
|
configInput: {};
|
|
1737
|
-
|
|
1738
|
-
|
|
1739
|
-
|
|
1740
|
-
|
|
1741
|
-
|
|
1742
|
-
[x: string]: ExtensionInput<AnyExtensionDataRef, {
|
|
1743
|
-
optional: boolean;
|
|
1744
|
-
singleton: boolean;
|
|
1745
|
-
}>;
|
|
1950
|
+
dataRefs: {
|
|
1951
|
+
component: ConfigurableExtensionDataRef<{
|
|
1952
|
+
ref: SwappableComponentRef;
|
|
1953
|
+
loader: (() => (props: {}) => JSX.Element | null) | (() => Promise<(props: {}) => JSX.Element | null>);
|
|
1954
|
+
}, "core.swappableComponent", {}>;
|
|
1746
1955
|
};
|
|
1747
|
-
params: never;
|
|
1748
|
-
kind: "component";
|
|
1749
|
-
name: string;
|
|
1750
1956
|
}>;
|
|
1751
|
-
/** @public */
|
|
1752
|
-
declare namespace createComponentExtension {
|
|
1753
|
-
const componentDataRef: ConfigurableExtensionDataRef<{
|
|
1754
|
-
ref: ComponentRef;
|
|
1755
|
-
impl: ComponentType;
|
|
1756
|
-
}, "core.component.component", {}>;
|
|
1757
|
-
}
|
|
1758
1957
|
|
|
1759
|
-
export { type AnalyticsApi, AnalyticsContext, type AnalyticsContextValue, type AnalyticsEvent, type AnalyticsEventAttributes, type
|
|
1958
|
+
export { type AnalyticsApi, AnalyticsContext, type AnalyticsContextValue, type AnalyticsEvent, type AnalyticsEventAttributes, type AnalyticsImplementation, AnalyticsImplementationBlueprint, type AnalyticsImplementationFactory, type AnalyticsTracker, type AnyExtensionDataRef, type AnyRouteRefParams, ApiBlueprint, type AppNode, type AppNodeEdges, type AppNodeInstance, type AppNodeSpec, AppRootElementBlueprint, AppRootWrapperBlueprint, type AppTree, type AppTreeApi, type ConfigurableExtensionDataRef, type CreateExtensionBlueprintOptions, type CreateExtensionOptions, type CreateFrontendFeatureLoaderOptions, type CreateFrontendModuleOptions, type CreateSwappableComponentOptions, type DialogApi, type DialogApiDialog, ErrorDisplay, type ErrorDisplayProps, type Extension, type ExtensionAttachToSpec, type ExtensionBlueprint, type ExtensionBlueprintDefineParams, type ExtensionBlueprintParameters, type ExtensionBlueprintParams, ExtensionBoundary, type ExtensionBoundaryProps, type ExtensionDataContainer, type ExtensionDataRef, type ExtensionDataRefToValue, type ExtensionDataValue, type ExtensionDefinition, type ExtensionDefinitionParameters, type ExtensionFactoryMiddleware, type ExtensionInput, type ExternalRouteRef, type FeatureFlagConfig, type FrontendFeature, type FrontendFeatureLoader, type FrontendModule, type FrontendPlugin, type FrontendPluginInfo, type FrontendPluginInfoOptions, IconBundleBlueprint, type IconComponent, type IconsApi, NavContentBlueprint, type NavContentComponent, type NavContentComponentProps, NavItemBlueprint, NotFoundErrorPage, type NotFoundErrorPageProps, PageBlueprint, type PluginOptions, type PortableSchema, Progress, type ProgressProps, type ResolvedExtensionInput, type ResolvedExtensionInputs, type RouteFunc, type RouteRef, type RouteResolutionApi, RouterBlueprint, SignInPageBlueprint, type SubRouteRef, SwappableComponentBlueprint, type SwappableComponentRef, type SwappableComponentsApi, ThemeBlueprint, TranslationBlueprint, analyticsApiRef, appTreeApiRef, coreExtensionData, createExtension, createExtensionBlueprint, createExtensionBlueprintParams, createExtensionDataRef, createExtensionInput, createExternalRouteRef, createFrontendFeatureLoader, createFrontendModule, createFrontendPlugin, createRouteRef, createSubRouteRef, createSwappableComponent, dialogApiRef, iconsApiRef, routeResolutionApiRef, swappableComponentsApiRef, useAnalytics, useAppNode, useRouteRef, useRouteRefParams };
|