add elements and wrappers to the app root

Signed-off-by: Fredrik Adelöw <freben@gmail.com>
2024-01-11 13:56:58 +01:00
parent 86baccb2d7
commit c97fa1c2bd
9 changed files with 514 additions and 21 deletions
@@ -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 {},
@@ -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();
+  });
+});
@@ -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,
+      };
+    },
+  });
+}
@@ -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();
+  });
+});
@@ -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',
+    );
+}
@@ -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';