;
+
+// @public (undocumented)
+export namespace createAppRootWrapperExtension {
+ const // (undocumented)
+ componentDataRef: ConfigurableExtensionDataRef<
+ React_2.ComponentType<{
+ children?: React_2.ReactNode;
+ }>,
+ {}
+ >;
+}
+
// @public (undocumented)
export function createComponentExtension<
TProps extends {},
diff --git a/packages/frontend-plugin-api/src/extensions/createAppRootElementExtension.test.tsx b/packages/frontend-plugin-api/src/extensions/createAppRootElementExtension.test.tsx
new file mode 100644
index 0000000000..c8bf6ee355
--- /dev/null
+++ b/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: Hello
,
+ });
+
+ 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 }) => (
+
+ Hello, {config.name}, {inputs.children.length}
+
+ ),
+ });
+
+ 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: }),
+ }),
+ )
+ .render();
+
+ await expect(
+ screen.findByText('Hello, Robin, 1'),
+ ).resolves.toBeInTheDocument();
+ });
+});
diff --git a/packages/frontend-plugin-api/src/extensions/createAppRootElementExtension.ts b/packages/frontend-plugin-api/src/extensions/createAppRootElementExtension.ts
new file mode 100644
index 0000000000..8be82d5540
--- /dev/null
+++ b/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;
+ disabled?: boolean;
+ inputs?: TInputs;
+ element:
+ | JSX.Element
+ | ((options: {
+ inputs: Expand>;
+ config: TConfig;
+ }) => JSX.Element);
+}): ExtensionDefinition {
+ 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,
+ };
+ },
+ });
+}
diff --git a/packages/frontend-plugin-api/src/extensions/createAppRootWrapperExtension.test.tsx b/packages/frontend-plugin-api/src/extensions/createAppRootWrapperExtension.test.tsx
new file mode 100644
index 0000000000..a0625ec1ae
--- /dev/null
+++ b/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: () => Hello
,
+ });
+
+ 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 () => ,
+ }),
+ )
+ .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 }) => (
+
+ {children}
+
+ ),
+ });
+
+ 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 () => Hello
,
+ }),
+ )
+ .add(extension, { config: { name: 'Robin' } })
+ .add(
+ createExtension({
+ attachTo: { id: 'app-wrapper-component:ns/test', input: 'children' },
+ output: { element: coreExtensionData.reactElement },
+ factory: () => ({ element: }),
+ }),
+ )
+ .render();
+
+ await expect(screen.findByText('Hello')).resolves.toBeInTheDocument();
+ await expect(screen.findByTestId('Robin-1')).resolves.toBeInTheDocument();
+ });
+});
diff --git a/packages/frontend-plugin-api/src/extensions/createAppRootWrapperExtension.tsx b/packages/frontend-plugin-api/src/extensions/createAppRootWrapperExtension.tsx
new file mode 100644
index 0000000000..1f09b873cc
--- /dev/null
+++ b/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;
+ disabled?: boolean;
+ inputs?: TInputs;
+ Component: ComponentType<
+ PropsWithChildren<{
+ inputs: Expand>;
+ config: TConfig;
+ }>
+ >;
+}): ExtensionDefinition {
+ 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 (
+
+ {props.children}
+
+ );
+ };
+ return {
+ component: Component,
+ };
+ },
+ });
+}
+
+/** @public */
+export namespace createAppRootWrapperExtension {
+ export const componentDataRef =
+ createExtensionDataRef>>(
+ 'app.root.wrapper',
+ );
+}
diff --git a/packages/frontend-plugin-api/src/extensions/index.ts b/packages/frontend-plugin-api/src/extensions/index.ts
index fd2e38de49..40e9f6f56d 100644
--- a/packages/frontend-plugin-api/src/extensions/index.ts
+++ b/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';
diff --git a/packages/frontend-test-utils/src/app/createExtensionTester.tsx b/packages/frontend-test-utils/src/app/createExtensionTester.tsx
index 1a4ebbac48..2984af9dbf 100644
--- a/packages/frontend-test-utils/src/app/createExtensionTester.tsx
+++ b/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 => (
+ {el.output.element}
+ ))}
+ {inputs.children.output.element}
+
+ );
+
+ for (const wrapper of inputs.wrappers) {
+ content = {content};
+ }
return {
element: (
- {children}
+ {content}
),
@@ -278,8 +301,8 @@ export class ExtensionTester {
createExtensionOverrides({
extensions: [
...this.#extensions.map(extension => extension.definition),
- TestCoreNavExtension,
- TestCoreRouterExtension,
+ TestAppNavExtension,
+ TestAppRootExtension,
],
}),
],