@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.
Files changed (61) hide show
  1. package/CHANGELOG.md +211 -0
  2. package/dist/analytics/useAnalytics.esm.js +1 -1
  3. package/dist/apis/definitions/AnalyticsApi.esm.js.map +1 -1
  4. package/dist/apis/definitions/AppTreeApi.esm.js.map +1 -1
  5. package/dist/apis/definitions/DialogApi.esm.js.map +1 -1
  6. package/dist/apis/definitions/RouteResolutionApi.esm.js.map +1 -1
  7. package/dist/apis/definitions/SwappableComponentsApi.esm.js +8 -0
  8. package/dist/apis/definitions/SwappableComponentsApi.esm.js.map +1 -0
  9. package/dist/blueprints/AnalyticsImplementationBlueprint.esm.js +24 -0
  10. package/dist/blueprints/AnalyticsImplementationBlueprint.esm.js.map +1 -0
  11. package/dist/blueprints/AppRootElementBlueprint.esm.js +1 -3
  12. package/dist/blueprints/AppRootElementBlueprint.esm.js.map +1 -1
  13. package/dist/blueprints/AppRootWrapperBlueprint.esm.js +1 -5
  14. package/dist/blueprints/AppRootWrapperBlueprint.esm.js.map +1 -1
  15. package/dist/blueprints/PageBlueprint.esm.js +17 -9
  16. package/dist/blueprints/PageBlueprint.esm.js.map +1 -1
  17. package/dist/blueprints/RouterBlueprint.esm.js +2 -2
  18. package/dist/blueprints/RouterBlueprint.esm.js.map +1 -1
  19. package/dist/blueprints/SignInPageBlueprint.esm.js +9 -1
  20. package/dist/blueprints/SignInPageBlueprint.esm.js.map +1 -1
  21. package/dist/blueprints/SwappableComponentBlueprint.esm.js +27 -0
  22. package/dist/blueprints/SwappableComponentBlueprint.esm.js.map +1 -0
  23. package/dist/components/DefaultSwappableComponents.esm.js +16 -0
  24. package/dist/components/DefaultSwappableComponents.esm.js.map +1 -0
  25. package/dist/components/ErrorBoundary.esm.js +3 -2
  26. package/dist/components/ErrorBoundary.esm.js.map +1 -1
  27. package/dist/components/ExtensionBoundary.esm.js +9 -16
  28. package/dist/components/ExtensionBoundary.esm.js.map +1 -1
  29. package/dist/components/createSwappableComponent.esm.js +52 -0
  30. package/dist/components/createSwappableComponent.esm.js.map +1 -0
  31. package/dist/frontend-internal/src/wiring/InternalExtensionDefinition.esm.js.map +1 -1
  32. package/dist/frontend-internal/src/wiring/InternalSwappableComponentRef.esm.js +9 -0
  33. package/dist/frontend-internal/src/wiring/InternalSwappableComponentRef.esm.js.map +1 -0
  34. package/dist/frontend-internal/src/wiring/createExtensionDataContainer.esm.js +4 -1
  35. package/dist/frontend-internal/src/wiring/createExtensionDataContainer.esm.js.map +1 -1
  36. package/dist/index.d.ts +493 -294
  37. package/dist/index.esm.js +5 -4
  38. package/dist/index.esm.js.map +1 -1
  39. package/dist/routing/RouteRef.esm.js +8 -2
  40. package/dist/routing/RouteRef.esm.js.map +1 -1
  41. package/dist/routing/useRouteRef.esm.js +1 -1
  42. package/dist/wiring/createExtension.esm.js +7 -0
  43. package/dist/wiring/createExtension.esm.js.map +1 -1
  44. package/dist/wiring/createExtensionBlueprint.esm.js +3 -2
  45. package/dist/wiring/createExtensionBlueprint.esm.js.map +1 -1
  46. package/dist/wiring/createExtensionDataRef.esm.js.map +1 -1
  47. package/dist/wiring/createFrontendModule.esm.js.map +1 -1
  48. package/dist/wiring/createFrontendPlugin.esm.js +2 -6
  49. package/dist/wiring/createFrontendPlugin.esm.js.map +1 -1
  50. package/dist/wiring/resolveExtensionDefinition.esm.js.map +1 -1
  51. package/dist/wiring/resolveInputOverrides.esm.js +3 -0
  52. package/dist/wiring/resolveInputOverrides.esm.js.map +1 -1
  53. package/package.json +5 -5
  54. package/dist/apis/definitions/ComponentsApi.esm.js +0 -12
  55. package/dist/apis/definitions/ComponentsApi.esm.js.map +0 -1
  56. package/dist/components/coreComponentRefs.esm.js +0 -19
  57. package/dist/components/coreComponentRefs.esm.js.map +0 -1
  58. package/dist/components/createComponentRef.esm.js +0 -12
  59. package/dist/components/createComponentRef.esm.js.map +0 -1
  60. package/dist/extensions/createComponentExtension.esm.js +0 -43
  61. 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, PropsWithChildren } from 'react';
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
- * Common analytics context attributes.
15
+ * Analytics context envelope.
16
16
  *
17
17
  * @public
18
18
  */
19
- type CommonAnalyticsContext = {
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
- /** @public */
72
- type AnyExtensionDataRef = ExtensionDataRef<unknown, string, {
73
- optional?: true;
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: string extends TParamKeys ? (keyof TParams)[] : TParamKeys[];
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
- /** @public */
167
- type ResolveInputValueOverrides<TInputs extends {
168
- [inputName in string]: ExtensionInput<AnyExtensionDataRef, {
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<AnyExtensionDataRef, {
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 AnyRoutes = AnyRoutes, TExternalRoutes extends AnyExternalRoutes = AnyExternalRoutes, TExtensionMap 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 AnyRoutes, TExternalRoutes extends AnyExternalRoutes, TExtensions extends readonly ExtensionDefinition[]> {
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 AnyRoutes = {}, TExternalRoutes extends AnyExternalRoutes = {}, TExtensions extends readonly ExtensionDefinition[] = []>(options: Omit<PluginOptions<TId, TRoutes, TExternalRoutes, TExtensions>, 'pluginId'> & {
491
- id: string;
492
- }): FrontendPlugin<TRoutes, TExternalRoutes, MakeSortedExtensionsMap<TExtensions[number], TId>>;
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 AnyRoutes = {
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<AnyExtensionDataRef>, context: {
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 ExtensionBlueprintParamsDefiner<TParams extends object = object, TInput = any> = (params: TInput) => ExtensionBlueprintParams<TParams>;
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, TName extends string | undefined, TParams extends object | ExtensionBlueprintParamsDefiner, UOutput extends AnyExtensionDataRef, TInputs extends {
569
- [inputName in string]: ExtensionInput<AnyExtensionDataRef, {
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]: AnyExtensionDataRef;
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: define => define({
682
+ * params: defineParams => defineParams({
619
683
  * component: ...,
620
684
  * fetcher: ...,
621
685
  * }),
622
686
  * });
623
687
  * ```
624
688
  */
625
- defineParams?: TParams extends ExtensionBlueprintParamsDefiner ? TParams : 'The defineParams option must be a function if provided, see the docs for details';
626
- factory(params: TParams extends ExtensionBlueprintParamsDefiner ? ReturnType<TParams>['T'] : TParams, context: {
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
- name?: string;
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?: AnyExtensionDataRef;
710
+ output?: ExtensionDataRef;
648
711
  inputs?: {
649
- [KName in string]: ExtensionInput<AnyExtensionDataRef, {
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]: AnyExtensionDataRef;
718
+ [name in string]: ExtensionDataRef;
656
719
  };
657
720
  };
658
721
  /** @ignore */
659
- type ParamsFactory<TDefiner extends ExtensionBlueprintParamsDefiner> = (define: TDefiner) => ReturnType<TDefiner>;
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 | ExtensionBlueprintParamsDefiner> = TParams extends ExtensionBlueprintParamsDefiner<infer IParams> ? IParams | ParamsFactory<TParams> : TParams | ParamsFactory<ExtensionBlueprintParamsDefiner<TParams, TParams>>;
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<TNewName extends string | undefined, TParamsInput extends AnyParamsInput$1<NonNullable<T['params']>>>(args: {
673
- name?: TNewName;
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 ExtensionBlueprintParamsDefiner ? TParamsInput : T['params'] extends ExtensionBlueprintParamsDefiner ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `<blueprint>.make({ params: define => define(<params>) })`' : TParamsInput;
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 TNewName ? T['name'] : TNewName;
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<TNewName extends string | undefined, TExtensionConfigSchema extends {
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 AnyExtensionDataRef, TExtraInputs extends {
695
- [inputName in string]: ExtensionInput<AnyExtensionDataRef, {
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?: TNewName;
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 ExtensionBlueprintParamsDefiner ? TParamsInput : T['params'] extends ExtensionBlueprintParamsDefiner ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `originalFactory(define => define(<params>))`' : TParamsInput, context?: {
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?: ResolveInputValueOverrides<NonNullable<T['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<AnyExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UFactoryOutput>;
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: AnyExtensionDataRef extends UNewOutput ? T['output'] : UNewOutput;
793
+ output: ExtensionDataRef extends UNewOutput ? T['output'] : UNewOutput;
731
794
  inputs: T['inputs'] & TExtraInputs;
732
795
  kind: T['kind'];
733
- name: string | undefined extends TNewName ? T['name'] : TNewName;
796
+ name: string | undefined extends TName ? undefined : TName;
734
797
  params: T['params'];
735
798
  }>;
736
799
  }
737
800
  /**
738
- * A simpler replacement for wrapping up `createExtension` inside a kind or type. This allows for a cleaner API for creating
739
- * types and instances of those types.
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 | ExtensionBlueprintParamsDefiner, UOutput extends AnyExtensionDataRef, TInputs extends {
744
- [inputName in string]: ExtensionInput<AnyExtensionDataRef, {
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, TName extends string | undefined = undefined, TDataRefs extends {
751
- [name in string]: AnyExtensionDataRef;
752
- } = never>(options: CreateExtensionBlueprintOptions<TKind, TName, TParams, UOutput, TInputs, TConfigSchema, UFactoryOutput, TDataRefs>): ExtensionBlueprint<{
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<AnyExtensionDataRef> ? {
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 AnyExtensionDataRef, 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;
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 AnyExtensionDataRef, TInputs extends {
799
- [inputName in string]: ExtensionInput<AnyExtensionDataRef, {
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?: AnyExtensionDataRef;
939
+ output?: ExtensionDataRef;
835
940
  inputs?: {
836
- [KName in string]: ExtensionInput<AnyExtensionDataRef, {
941
+ [KName in string]: ExtensionInput<ExtensionDataRef, {
837
942
  optional: boolean;
838
943
  singleton: boolean;
839
944
  }>;
840
945
  };
841
- params?: object | ExtensionBlueprintParamsDefiner;
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 | ExtensionBlueprintParamsDefiner> = TParams extends ExtensionBlueprintParamsDefiner<infer IParams> ? IParams | ((define: TParams) => ReturnType<TParams>) : TParams | ((define: ExtensionBlueprintParamsDefiner<TParams, TParams>) => ReturnType<ExtensionBlueprintParamsDefiner<TParams, TParams>>);
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 AnyExtensionDataRef, TExtraInputs extends {
856
- [inputName in string]: ExtensionInput<AnyExtensionDataRef, {
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?: ResolveInputValueOverrides<NonNullable<T['inputs']>>;
979
+ inputs?: ResolvedInputValueOverrides<NonNullable<T['inputs']>>;
875
980
  } & ([T['params']] extends [never] ? {} : {
876
- params?: TFactoryParamsReturn extends ExtensionBlueprintParamsDefiner ? TFactoryParamsReturn : T['params'] extends ExtensionBlueprintParamsDefiner ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `originalFactory(define => define(<params>))`' : Partial<T['params']>;
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 ExtensionBlueprintParamsDefiner ? TParamsInput : T['params'] extends ExtensionBlueprintParamsDefiner ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `originalFactory(define => define(<params>))`' : Partial<T['params']>;
887
- })> & VerifyExtensionFactoryOutput<AnyExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UFactoryOutput>): ExtensionDefinition<{
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: AnyExtensionDataRef extends UNewOutput ? T['output'] : UNewOutput;
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
- /** @public */
901
- declare function createExtension<UOutput extends AnyExtensionDataRef, TInputs extends {
902
- [inputName in string]: ExtensionInput<AnyExtensionDataRef, {
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?: FrontendPlugin;
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(sourcePath: string): {
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 ComponentRef<T extends {} = {}> = {
1195
+ type SwappableComponentRef<TInnerComponentProps extends {} = {}, TExternalComponentProps extends {} = TInnerComponentProps> = {
1067
1196
  id: string;
1068
- T: T;
1197
+ TProps: TInnerComponentProps;
1198
+ TExternalProps: TExternalComponentProps;
1199
+ $$type: '@backstage/SwappableComponentRef';
1069
1200
  };
1070
- /** @public */
1071
- declare function createComponentRef<T extends {} = {}>(options: {
1201
+ /**
1202
+ * Options for creating an SwappableComponent.
1203
+ *
1204
+ * @public
1205
+ */
1206
+ type CreateSwappableComponentOptions<TInnerComponentProps extends {}, TExternalComponentProps extends {} = TInnerComponentProps> = {
1072
1207
  id: string;
1073
- }): ComponentRef<T>;
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
- /** @public */
1089
- declare const coreComponentRefs: {
1090
- progress: ComponentRef<CoreProgressProps>;
1091
- notFoundErrorPage: ComponentRef<CoreNotFoundErrorPageProps>;
1092
- errorBoundaryFallback: ComponentRef<CoreErrorBoundaryFallbackProps>;
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
- interface ComponentsApi {
1116
- getComponent<T extends {}>(ref: ComponentRef<T>): ComponentType<T>;
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
- * The `ApiRef` of {@link ComponentsApi}.
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
- declare const componentsApiRef: _backstage_core_plugin_api.ApiRef<ComponentsApi>;
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 function useComponentRef<T extends {}>(ref: ComponentRef<T>): ComponentType<T>;
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 = unknown> {
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 = {}>(elementOrComponent: JSX.Element | ((props: {
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 = {}>(elementOrComponent: JSX.Element | ((props: {
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?: RouteResolutionApiResolveOptions): RouteFunc<TParams> | undefined;
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: ConfigurableExtensionDataRef<AnyApiFactory, "core.api.factory", {}>;
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 | (() => JSX.Element);
1679
+ element: JSX.Element;
1482
1680
  };
1483
- output: ConfigurableExtensionDataRef<react.JSX.Element, "core.reactElement", {}>;
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
- Component: ComponentType<PropsWithChildren<{}>>;
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: ConfigurableExtensionDataRef<ComponentType<{
1504
- children?: react.ReactNode | undefined;
1505
- }>, "app.root.wrapper", {}>;
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<ComponentType<{
1511
- children?: react.ReactNode | undefined;
1512
- }>, "app.root.wrapper", {}>;
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: ConfigurableExtensionDataRef<{
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.ConfigurableExtensionDataRef<NavContentComponent, "core.nav-content.component", {}>;
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: ConfigurableExtensionDataRef<{
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
- defaultPath: string;
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: ConfigurableExtensionDataRef<react.JSX.Element, "core.reactElement", {}> | ConfigurableExtensionDataRef<string, "core.routing.path", {}> | ConfigurableExtensionDataRef<RouteRef<AnyRouteRefParams>, "core.routing.ref", {
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
- Component: ComponentType<PropsWithChildren<{}>>;
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: ConfigurableExtensionDataRef<ComponentType<{
1648
- children?: react.ReactNode | undefined;
1649
- }>, "app.router.wrapper", {}>;
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<ComponentType<{
1655
- children?: react.ReactNode | undefined;
1656
- }>, "app.router.wrapper", {}>;
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: ConfigurableExtensionDataRef<ComponentType<SignInPageProps>, "core.sign-in-page.component", {}>;
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: ConfigurableExtensionDataRef<AppTheme, "core.theme.theme", {}>;
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: ConfigurableExtensionDataRef<TranslationResource<string> | TranslationMessages<string, {
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
- /** @public */
1725
- declare function createComponentExtension<TProps extends {}>(options: {
1726
- ref: ComponentRef<TProps>;
1727
- name?: string;
1728
- disabled?: boolean;
1729
- loader: {
1730
- lazy: () => Promise<ComponentType<TProps>>;
1731
- } | {
1732
- sync: () => ComponentType<TProps>;
1733
- };
1734
- }): ExtensionDefinition<{
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
- output: ConfigurableExtensionDataRef<{
1738
- ref: ComponentRef;
1739
- impl: ComponentType;
1740
- }, "core.component.component", {}>;
1741
- inputs: {
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 AnalyticsTracker, type AnyExtensionDataRef, type AnyExternalRoutes, type AnyRouteRefParams, type AnyRoutes, ApiBlueprint, type AppNode, type AppNodeEdges, type AppNodeInstance, type AppNodeSpec, AppRootElementBlueprint, AppRootWrapperBlueprint, type AppTree, type AppTreeApi, type CommonAnalyticsContext, type ComponentRef, type ComponentsApi, type ConfigurableExtensionDataRef, type CoreErrorBoundaryFallbackProps, type CoreNotFoundErrorPageProps, type CoreProgressProps, type CreateExtensionBlueprintOptions, type CreateExtensionOptions, type CreateFrontendFeatureLoaderOptions, type CreateFrontendModuleOptions, type DialogApi, type DialogApiDialog, type Extension, type ExtensionAttachToSpec, type ExtensionBlueprint, type ExtensionBlueprintParameters, type ExtensionBlueprintParams, type ExtensionBlueprintParamsDefiner, 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, PageBlueprint, type PluginOptions, type PortableSchema, type ResolveInputValueOverrides, type ResolvedExtensionInput, type ResolvedExtensionInputs, type RouteFunc, type RouteRef, type RouteResolutionApi, type RouteResolutionApiResolveOptions, RouterBlueprint, SignInPageBlueprint, type SubRouteRef, ThemeBlueprint, TranslationBlueprint, analyticsApiRef, appTreeApiRef, componentsApiRef, coreComponentRefs, coreExtensionData, createComponentExtension, createComponentRef, createExtension, createExtensionBlueprint, createExtensionBlueprintParams, createExtensionDataRef, createExtensionInput, createExternalRouteRef, createFrontendFeatureLoader, createFrontendModule, createFrontendPlugin, createRouteRef, createSubRouteRef, dialogApiRef, iconsApiRef, routeResolutionApiRef, useAnalytics, useAppNode, useComponentRef, useRouteRef, useRouteRefParams };
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 };