add elements and wrappers to the app root

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

.changeset/silent-horses-raise.md

@@ -0,0 +1,7 @@
+---
+'@backstage/frontend-plugin-api': patch
+'@backstage/frontend-test-utils': patch
+'@backstage/frontend-app-api': patch
+---
+
+Added `elements` and `wrappers` inputs to `app/root`, that let you add things to the root of the React tree above the layout. You can use the `createAppRootElementExtension` and `createAppRootWrapperExtension` extension creator, respectively, to conveniently create such extensions.

packages/frontend-app-api/src/extensions/AppRoot.tsx

@@ -14,9 +14,16 @@
  * limitations under the License.
  */
 
-import React, { ComponentType, ReactNode, useContext, useState } from 'react';
+import React, {
+  ComponentType,
+  Fragment,
+  ReactNode,
+  useContext,
+  useState,
+} from 'react';
 import {
   coreExtensionData,
+  createAppRootWrapperExtension,
   createExtension,
   createExtensionInput,
   createSignInPageExtension,
@@ -40,26 +47,43 @@ export const AppRoot = createExtension({
   attachTo: { id: 'app', input: 'root' },
   inputs: {
     signInPage: createExtensionInput(
-      {
-        component: createSignInPageExtension.componentDataRef,
-      },
+      { component: createSignInPageExtension.componentDataRef },
       { singleton: true, optional: true },
     ),
     children: createExtensionInput(
-      {
-        element: coreExtensionData.reactElement,
-      },
+      { element: coreExtensionData.reactElement },
       { singleton: true },
     ),
+    elements: createExtensionInput(
+      { element: coreExtensionData.reactElement },
+      { optional: true },
+    ),
+    wrappers: createExtensionInput(
+      { component: createAppRootWrapperExtension.componentDataRef },
+      { optional: true },
+    ),
   },
   output: {
     element: coreExtensionData.reactElement,
   },
   factory({ inputs }) {
+    let content: React.ReactNode = (
+      <>
+        {inputs.elements.map(el => (
+          <Fragment key={el.node.spec.id}>{el.output.element}</Fragment>
+        ))}
+        {inputs.children.output.element}
+      </>
+    );
+
+    for (const wrapper of inputs.wrappers) {
+      content = <wrapper.output.component>{content}</wrapper.output.component>;
+    }
+
     return {
       element: (
         <AppRouter SignInPageComponent={inputs.signInPage?.output.component}>
-          {inputs.children.output.element}
+          {content}
         </AppRouter>
       ),
     };

packages/frontend-plugin-api/api-report.md

@@ -67,6 +67,7 @@ import { OpenIdConnectApi } from '@backstage/core-plugin-api';
 import { PendingOAuthRequest } from '@backstage/core-plugin-api';
 import { ProfileInfo } from '@backstage/core-plugin-api';
 import { ProfileInfoApi } from '@backstage/core-plugin-api';
+import { PropsWithChildren } from 'react';
 import { default as React_2 } from 'react';
 import { ReactNode } from 'react';
 import { SessionApi } from '@backstage/core-plugin-api';
@@ -390,6 +391,61 @@ export { createApiFactory };
 
 export { createApiRef };
 
+// @public
+export function createAppRootElementExtension<
+  TConfig extends {},
+  TInputs extends AnyExtensionInputMap,
+>(options: {
+  namespace?: string;
+  name?: string;
+  attachTo?: {
+    id: string;
+    input: string;
+  };
+  configSchema?: PortableSchema<TConfig>;
+  disabled?: boolean;
+  inputs?: TInputs;
+  element:
+    | JSX_2.Element
+    | ((options: {
+        inputs: Expand<ResolvedExtensionInputs<TInputs>>;
+        config: TConfig;
+      }) => JSX_2.Element);
+}): ExtensionDefinition<TConfig>;
+
+// @public
+export function createAppRootWrapperExtension<
+  TConfig extends {},
+  TInputs extends AnyExtensionInputMap,
+>(options: {
+  namespace?: string;
+  name?: string;
+  attachTo?: {
+    id: string;
+    input: string;
+  };
+  configSchema?: PortableSchema<TConfig>;
+  disabled?: boolean;
+  inputs?: TInputs;
+  Component: ComponentType<
+    PropsWithChildren<{
+      inputs: Expand<ResolvedExtensionInputs<TInputs>>;
+      config: TConfig;
+    }>
+  >;
+}): ExtensionDefinition<TConfig>;
+
+// @public (undocumented)
+export namespace createAppRootWrapperExtension {
+  const // (undocumented)
+    componentDataRef: ConfigurableExtensionDataRef<
+      React_2.ComponentType<{
+        children?: React_2.ReactNode;
+      }>,
+      {}
+    >;
+}
+
 // @public (undocumented)
 export function createComponentExtension<
   TProps extends {},

packages/frontend-plugin-api/src/extensions/createAppRootElementExtension.test.tsx

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createExtensionTester } from '@backstage/frontend-test-utils';
+import { screen } from '@testing-library/react';
+import React from 'react';
+import { createSchemaFromZod } from '../schema/createSchemaFromZod';
+import { coreExtensionData } from '../wiring/coreExtensionData';
+import { createExtension } from '../wiring/createExtension';
+import { createExtensionInput } from '../wiring/createExtensionInput';
+import { createAppRootElementExtension } from './createAppRootElementExtension';
+
+describe('createAppRootElementExtension', () => {
+  it('works with simple options and just an element', async () => {
+    const extension = createAppRootElementExtension({
+      element: <div>Hello</div>,
+    });
+
+    expect(extension).toEqual({
+      $$type: '@backstage/ExtensionDefinition',
+      version: 'v1',
+      kind: 'app-root-element',
+      attachTo: { id: 'app/root', input: 'elements' },
+      disabled: false,
+      inputs: {},
+      output: {
+        element: expect.anything(),
+      },
+      factory: expect.any(Function),
+      toString: expect.any(Function),
+    });
+
+    createExtensionTester(extension).render();
+
+    await expect(screen.findByText('Hello')).resolves.toBeInTheDocument();
+  });
+
+  it('works with complex options and a callback', async () => {
+    const schema = createSchemaFromZod(z => z.object({ name: z.string() }));
+
+    const extension = createAppRootElementExtension({
+      namespace: 'ns',
+      name: 'test',
+      configSchema: schema,
+      attachTo: { id: 'other', input: 'slot' },
+      disabled: true,
+      inputs: {
+        children: createExtensionInput({
+          element: coreExtensionData.reactElement,
+        }),
+      },
+      element: ({ inputs, config }) => (
+        <div>
+          Hello, {config.name}, {inputs.children.length}
+        </div>
+      ),
+    });
+
+    expect(extension).toEqual({
+      $$type: '@backstage/ExtensionDefinition',
+      version: 'v1',
+      kind: 'app-root-element',
+      namespace: 'ns',
+      name: 'test',
+      attachTo: { id: 'other', input: 'slot' },
+      configSchema: schema,
+      disabled: true,
+      inputs: {
+        children: createExtensionInput({
+          element: coreExtensionData.reactElement,
+        }),
+      },
+      output: {
+        element: expect.anything(),
+      },
+      factory: expect.any(Function),
+      toString: expect.any(Function),
+    });
+
+    createExtensionTester(extension, { config: { name: 'Robin' } })
+      .add(
+        createExtension({
+          attachTo: { id: 'app-root-element:ns/test', input: 'children' },
+          output: { element: coreExtensionData.reactElement },
+          factory: () => ({ element: <div /> }),
+        }),
+      )
+      .render();
+
+    await expect(
+      screen.findByText('Hello, Robin, 1'),
+    ).resolves.toBeInTheDocument();
+  });
+});

packages/frontend-plugin-api/src/extensions/createAppRootElementExtension.ts

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { JSX } from 'react';
+import { PortableSchema } from '../schema/types';
+import { Expand } from '../types';
+import { coreExtensionData } from '../wiring/coreExtensionData';
+import {
+  AnyExtensionInputMap,
+  ExtensionDefinition,
+  ResolvedExtensionInputs,
+  createExtension,
+} from '../wiring/createExtension';
+
+/**
+ * Creates an extension that renders a React element at the app root, outside of
+ * the app layout. This is useful for example for shared popups and similar.
+ *
+ * @public
+ */
+export function createAppRootElementExtension<
+  TConfig extends {},
+  TInputs extends AnyExtensionInputMap,
+>(options: {
+  namespace?: string;
+  name?: string;
+  attachTo?: { id: string; input: string };
+  configSchema?: PortableSchema<TConfig>;
+  disabled?: boolean;
+  inputs?: TInputs;
+  element:
+    | JSX.Element
+    | ((options: {
+        inputs: Expand<ResolvedExtensionInputs<TInputs>>;
+        config: TConfig;
+      }) => JSX.Element);
+}): ExtensionDefinition<TConfig> {
+  return createExtension({
+    kind: 'app-root-element',
+    namespace: options.namespace,
+    name: options.name,
+    attachTo: options.attachTo ?? { id: 'app/root', input: 'elements' },
+    configSchema: options.configSchema,
+    disabled: options.disabled,
+    inputs: options.inputs,
+    output: {
+      element: coreExtensionData.reactElement,
+    },
+    factory({ inputs, config }) {
+      return {
+        element:
+          typeof options.element === 'function'
+            ? options.element({ inputs, config })
+            : options.element,
+      };
+    },
+  });
+}

packages/frontend-plugin-api/src/extensions/createAppRootWrapperExtension.test.tsx

@@ -0,0 +1,119 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createExtensionTester } from '@backstage/frontend-test-utils';
+import { screen } from '@testing-library/react';
+import React from 'react';
+import { createSchemaFromZod } from '../schema/createSchemaFromZod';
+import { coreExtensionData } from '../wiring/coreExtensionData';
+import { createExtension } from '../wiring/createExtension';
+import { createExtensionInput } from '../wiring/createExtensionInput';
+import { createAppRootWrapperExtension } from './createAppRootWrapperExtension';
+import { createPageExtension } from './createPageExtension';
+
+describe('createAppRootWrapperExtension', () => {
+  it('works with simple options and no props', async () => {
+    const extension = createAppRootWrapperExtension({
+      Component: () => <div>Hello</div>,
+    });
+
+    expect(extension).toEqual({
+      $$type: '@backstage/ExtensionDefinition',
+      version: 'v1',
+      kind: 'app-wrapper-component',
+      attachTo: { id: 'app/root', input: 'wrappers' },
+      disabled: false,
+      inputs: {},
+      output: {
+        component: expect.anything(),
+      },
+      factory: expect.any(Function),
+      toString: expect.any(Function),
+    });
+
+    createExtensionTester(
+      createPageExtension({
+        defaultPath: '/',
+        loader: async () => <div />,
+      }),
+    )
+      .add(extension)
+      .render();
+
+    await expect(screen.findByText('Hello')).resolves.toBeInTheDocument();
+  });
+
+  it('works with complex options and props', async () => {
+    const schema = createSchemaFromZod(z => z.object({ name: z.string() }));
+
+    const extension = createAppRootWrapperExtension({
+      namespace: 'ns',
+      name: 'test',
+      configSchema: schema,
+      disabled: true,
+      inputs: {
+        children: createExtensionInput({
+          element: coreExtensionData.reactElement,
+        }),
+      },
+      Component: ({ inputs, config, children }) => (
+        <div data-testid={`${config.name}-${inputs.children.length}`}>
+          {children}
+        </div>
+      ),
+    });
+
+    expect(extension).toEqual({
+      $$type: '@backstage/ExtensionDefinition',
+      version: 'v1',
+      kind: 'app-wrapper-component',
+      namespace: 'ns',
+      name: 'test',
+      attachTo: { id: 'app/root', input: 'wrappers' },
+      configSchema: schema,
+      disabled: true,
+      inputs: {
+        children: createExtensionInput({
+          element: coreExtensionData.reactElement,
+        }),
+      },
+      output: {
+        component: expect.anything(),
+      },
+      factory: expect.any(Function),
+      toString: expect.any(Function),
+    });
+
+    createExtensionTester(
+      createPageExtension({
+        defaultPath: '/',
+        loader: async () => <div>Hello</div>,
+      }),
+    )
+      .add(extension, { config: { name: 'Robin' } })
+      .add(
+        createExtension({
+          attachTo: { id: 'app-wrapper-component:ns/test', input: 'children' },
+          output: { element: coreExtensionData.reactElement },
+          factory: () => ({ element: <div /> }),
+        }),
+      )
+      .render();
+
+    await expect(screen.findByText('Hello')).resolves.toBeInTheDocument();
+    await expect(screen.findByTestId('Robin-1')).resolves.toBeInTheDocument();
+  });
+});

packages/frontend-plugin-api/src/extensions/createAppRootWrapperExtension.tsx

@@ -0,0 +1,84 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React, { ComponentType, PropsWithChildren } from 'react';
+import { PortableSchema } from '../schema/types';
+import {
+  AnyExtensionInputMap,
+  ExtensionDefinition,
+  ResolvedExtensionInputs,
+  createExtension,
+} from '../wiring/createExtension';
+import { createExtensionDataRef } from '../wiring/createExtensionDataRef';
+import { Expand } from '../types';
+
+/**
+ * Creates an extension that renders a React wrapper at the app root, enclosing
+ * the app layout. This is useful for example for adding global React contexts
+ * and similar.
+ *
+ * @public
+ */
+export function createAppRootWrapperExtension<
+  TConfig extends {},
+  TInputs extends AnyExtensionInputMap,
+>(options: {
+  namespace?: string;
+  name?: string;
+  attachTo?: { id: string; input: string };
+  configSchema?: PortableSchema<TConfig>;
+  disabled?: boolean;
+  inputs?: TInputs;
+  Component: ComponentType<
+    PropsWithChildren<{
+      inputs: Expand<ResolvedExtensionInputs<TInputs>>;
+      config: TConfig;
+    }>
+  >;
+}): ExtensionDefinition<TConfig> {
+  return createExtension({
+    kind: 'app-wrapper-component',
+    namespace: options.namespace,
+    name: options.name,
+    attachTo: options.attachTo ?? { id: 'app/root', input: 'wrappers' },
+    configSchema: options.configSchema,
+    disabled: options.disabled,
+    inputs: options.inputs,
+    output: {
+      component: createAppRootWrapperExtension.componentDataRef,
+    },
+    factory({ inputs, config }) {
+      const Component = (props: PropsWithChildren<{}>) => {
+        return (
+          <options.Component inputs={inputs} config={config}>
+            {props.children}
+          </options.Component>
+        );
+      };
+      return {
+        component: Component,
+      };
+    },
+  });
+}
+
+/** @public */
+export namespace createAppRootWrapperExtension {
+  export const componentDataRef =
+    createExtensionDataRef<ComponentType<PropsWithChildren<{}>>>(
+      'app.root.wrapper',
+    );
+}

packages/frontend-plugin-api/src/extensions/index.ts

@@ -15,6 +15,8 @@
  */
 
 export { createApiExtension } from './createApiExtension';
+export { createAppRootElementExtension } from './createAppRootElementExtension';
+export { createAppRootWrapperExtension } from './createAppRootWrapperExtension';
 export { createPageExtension } from './createPageExtension';
 export { createNavItemExtension } from './createNavItemExtension';
 export { createNavLogoExtension } from './createNavLogoExtension';

packages/frontend-test-utils/src/app/createExtensionTester.tsx

@@ -14,7 +14,13 @@
  * limitations under the License.
  */
 
-import React, { ComponentType, ReactNode, useContext, useState } from 'react';
+import React, {
+  ComponentType,
+  Fragment,
+  ReactNode,
+  useContext,
+  useState,
+} from 'react';
 import { MemoryRouter, Link } from 'react-router-dom';
 import { RenderResult, render } from '@testing-library/react';
 import { createSpecializedApp } from '@backstage/frontend-app-api';
@@ -25,6 +31,7 @@ import {
   RouteRef,
   configApiRef,
   coreExtensionData,
+  createAppRootWrapperExtension,
   createExtension,
   createExtensionInput,
   createExtensionOverrides,
@@ -63,7 +70,7 @@ const NavItem = (props: {
   );
 };
 
-const TestCoreNavExtension = createExtension({
+const TestAppNavExtension = createExtension({
   namespace: 'app',
   name: 'nav',
   attachTo: { id: 'app/layout', input: 'nav' },
@@ -149,36 +156,52 @@ const AuthenticationProvider = (props: {
   return children;
 };
 
-const TestCoreRouterExtension = createExtension({
+const TestAppRootExtension = createExtension({
   namespace: 'app',
   name: 'root',
   attachTo: { id: 'app', input: 'root' },
   inputs: {
     signInPage: createExtensionInput(
-      {
-        component: createSignInPageExtension.componentDataRef,
-      },
+      { component: createSignInPageExtension.componentDataRef },
       { singleton: true, optional: true },
     ),
     children: createExtensionInput(
-      {
-        element: coreExtensionData.reactElement,
-      },
+      { element: coreExtensionData.reactElement },
       { singleton: true },
     ),
+    elements: createExtensionInput(
+      { element: coreExtensionData.reactElement },
+      { optional: true },
+    ),
+    wrappers: createExtensionInput(
+      { component: createAppRootWrapperExtension.componentDataRef },
+      { optional: true },
+    ),
   },
   output: {
     element: coreExtensionData.reactElement,
   },
   factory({ inputs }) {
     const SignInPage = inputs.signInPage?.output.component;
-    const children = inputs.children.output.element;
+
+    let content: React.ReactNode = (
+      <>
+        {inputs.elements.map(el => (
+          <Fragment key={el.node.spec.id}>{el.output.element}</Fragment>
+        ))}
+        {inputs.children.output.element}
+      </>
+    );
+
+    for (const wrapper of inputs.wrappers) {
+      content = <wrapper.output.component>{content}</wrapper.output.component>;
+    }
 
     return {
       element: (
         <MemoryRouter>
           <AuthenticationProvider signInPage={SignInPage}>
-            {children}
+            {content}
           </AuthenticationProvider>
         </MemoryRouter>
       ),
@@ -278,8 +301,8 @@ export class ExtensionTester {
         createExtensionOverrides({
           extensions: [
             ...this.#extensions.map(extension => extension.definition),
-            TestCoreNavExtension,
-            TestCoreRouterExtension,
+            TestAppNavExtension,
+            TestAppRootExtension,
           ],
         }),
       ],