Merge pull request #30858 from backstage/blam/swappable/docs

`componentRefs`: updating the default ID's and relevant docs

docs/frontend-system/building-apps/03-built-in-extensions.md

@@ -59,11 +59,11 @@ Extensions that provides default theme inputs for the `App` extension.
 
 Extensions that provides default components inputs for the `App` extension.
 
-|    kind    | namespace |               name                |                         id                         |
-| :--------: | :-------: | :-------------------------------: | :------------------------------------------------: |
-| components |    app    |     core.components.progress      |     `components:app/core.components.progress`      |
-| components |    app    | core.components.notFoundErrorPage | `components:app/core.components.notFoundErrorPage` |
-| components |    app    |   core.components.errorDisplay    |   `components:app/core.components.errorDisplay`    |
+|    kind    | namespace |           name            |                     id                     |
+| :--------: | :-------: | :-----------------------: | :----------------------------------------: |
+| components |    app    |       core-progress       |       `components:app/core-progress`       |
+| components |    app    | core-not-found-error-page | `components:app/core-not-found-error-page` |
+| components |    app    |    core-error-display     |    `components:app/core-error-display`     |
 
 #### Default apis extensions
 

docs/frontend-system/building-plugins/06-swappable-components.md

@@ -49,7 +49,7 @@ import { ExampleSwappableComponent } from '@internal/plugin-example-react';
 ## Overriding a Swappable Component
 
 In order to override a Swappable Component, you need to create a `SwappableComponentBlueprint` and install it with the `app` plugin.
-There's two different ways to add extensions to the `app` plugin, both are documented below in an example of overriding the `Progress` Swappable Component.
+There are two different ways to add extensions to the `app` plugin, both are documented below in an example of overriding the `Progress` Swappable Component.
 
 ```tsx title="in packages/app/src/App.tsx"
 import {
@@ -63,25 +63,12 @@ import appPlugin from '@backstage/plugin-app';
 
 const app = createApp({
   features: [
-    // Override an existing extension by ID provided by the app plugin:
-    appPlugin.withOverrides({
-      extensions: [
-        appPlugin
-          .getExtension('component:app/core.components.progress')
-          .override({
-            params: defineParams =>
-              defineParams({
-                component: Progress,
-                loader: () => MyCustomProgress,
-              }),
-          }),
-      ],
-    }),
-    // OR: Add another extension but with the same component ID:
-    appPlugin.withOverrides({
+    // Using a module to provide the extenion to the app
+    createFrontendModule({
+      pluginId: 'app',
       extensions: [
         SwappableComponentBlueprint.make({
-          name: 'core.components.progress',
+          name: 'core-progress',
           params: defineParams =>
             defineParams({
               component: Progress,
@@ -90,12 +77,10 @@ const app = createApp({
         }),
       ],
     }),
-    // OR: Use a module for the app plugin:
-    createFrontendModule({
-      pluginId: 'app',
+    // Core components that already ship with the app plugin can be overriden using getExtension()
+    appPlugin.withOverrides({
       extensions: [
-        SwappableComponentBlueprint.make({
-          name: 'core.components.progress',
+        appPlugin.getExtension('component:app/core-progress').override({
           params: defineParams =>
             defineParams({
               component: Progress,
@@ -110,7 +95,7 @@ const app = createApp({
 
 ## Default Swappable Components
 
-Currently there is only three different built-in Swappable Components that you can replace the implementations of, and these live in `@backstage/frontend-plugin-api`. They are as follows:
+Currently there are only three different built-in Swappable Components that you can replace the implementations of, and these live in `@backstage/frontend-plugin-api`. They are as follows:
 
 - `<Progress />
 - `<ErrorDisplay />

packages/frontend-defaults/src/createApp.test.tsx

@@ -384,9 +384,9 @@ describe('createApp', () => {
           </api:app/app-theme>
           <api:app/swappable-components out=[core.api.factory]>
             components [
-              <component:app/core.components.progress out=[core.swappableComponent] />
-              <component:app/core.components.notFoundErrorPage out=[core.swappableComponent] />
-              <component:app/core.components.errorBoundary out=[core.swappableComponent] />
+              <component:app/core-progress out=[core.swappableComponent] />
+              <component:app/core-not-found-error-page out=[core.swappableComponent] />
+              <component:app/core-error-display out=[core.swappableComponent] />
             ]
           </api:app/swappable-components>
           <api:app/icons out=[core.api.factory] />

packages/frontend-plugin-api/src/components/DefaultSwappableComponents.tsx

@@ -25,7 +25,7 @@ import { createSwappableComponent } from './createSwappableComponent';
  * @public
  */
 export const Progress = createSwappableComponent<ProgressProps>({
-  id: 'core.components.progress',
+  id: 'core-progress',
 });
 
 /**
@@ -33,14 +33,14 @@ export const Progress = createSwappableComponent<ProgressProps>({
  */
 export const NotFoundErrorPage =
   createSwappableComponent<NotFoundErrorPageProps>({
-    id: 'core.components.notFoundErrorPage',
+    id: 'core-not-found-error-page',
   });
 
 /**
  * @public
  */
 export const ErrorDisplay = createSwappableComponent<ErrorDisplayProps>({
-  id: 'core.components.errorDisplay',
+  id: 'core-error-display',
   loader: () => props =>
-    <div data-testid="core.components.errorDisplay">{props.error.message}</div>,
+    <div data-testid="core-error-display">{props.error.message}</div>,
 });

plugins/app/report.api.md

@@ -743,9 +743,9 @@ const appPlugin: FrontendPlugin<
         element: JSX.Element;
       };
     }>;
-    'component:app/core.components.errorBoundary': ExtensionDefinition<{
+    'component:app/core-error-display': ExtensionDefinition<{
       kind: 'component';
-      name: 'core.components.errorBoundary';
+      name: 'core-error-display';
       config: {};
       configInput: {};
       output: ExtensionDataRef<
@@ -799,9 +799,9 @@ const appPlugin: FrontendPlugin<
           : never;
       }>;
     }>;
-    'component:app/core.components.notFoundErrorPage': ExtensionDefinition<{
+    'component:app/core-not-found-error-page': ExtensionDefinition<{
       kind: 'component';
-      name: 'core.components.notFoundErrorPage';
+      name: 'core-not-found-error-page';
       config: {};
       configInput: {};
       output: ExtensionDataRef<
@@ -855,9 +855,9 @@ const appPlugin: FrontendPlugin<
           : never;
       }>;
     }>;
-    'component:app/core.components.progress': ExtensionDefinition<{
+    'component:app/core-progress': ExtensionDefinition<{
       kind: 'component';
-      name: 'core.components.progress';
+      name: 'core-progress';
       config: {};
       configInput: {};
       output: ExtensionDataRef<

plugins/app/src/extensions/components.tsx

@@ -28,7 +28,7 @@ import {
 import Button from '@material-ui/core/Button';
 
 export const Progress = SwappableComponentBlueprint.make({
-  name: 'core.components.progress',
+  name: 'core-progress',
   params: define =>
     define({
       component: SwappableProgress,
@@ -37,7 +37,7 @@ export const Progress = SwappableComponentBlueprint.make({
 });
 
 export const NotFoundErrorPage = SwappableComponentBlueprint.make({
-  name: 'core.components.notFoundErrorPage',
+  name: 'core-not-found-error-page',
   params: define =>
     define({
       component: SwappableNotFoundErrorPage,
@@ -46,8 +46,8 @@ export const NotFoundErrorPage = SwappableComponentBlueprint.make({
     }),
 });
 
-export const ErrorBoundary = SwappableComponentBlueprint.make({
-  name: 'core.components.errorBoundary',
+export const ErrorDisplay = SwappableComponentBlueprint.make({
+  name: 'core-error-display',
   params: define =>
     define({
       component: SwappableErrorDisplay,

plugins/app/src/extensions/index.ts

@@ -31,4 +31,4 @@ export {
   oauthRequestDialogAppRootElement,
   alertDisplayAppRootElement,
 } from './elements';
-export { Progress, NotFoundErrorPage, ErrorBoundary } from './components';
+export { Progress, NotFoundErrorPage, ErrorDisplay } from './components';

plugins/app/src/plugin.ts

@@ -35,7 +35,7 @@ import {
   dialogDisplayAppRootElement,
   Progress,
   NotFoundErrorPage,
-  ErrorBoundary,
+  ErrorDisplay,
   LegacyComponentsApi,
 } from './extensions';
 import { apis } from './defaultApis';
@@ -65,7 +65,7 @@ export const appPlugin = createFrontendPlugin({
     dialogDisplayAppRootElement,
     Progress,
     NotFoundErrorPage,
-    ErrorBoundary,
+    ErrorDisplay,
     LegacyComponentsApi,
   ],
 });