Merge pull request #26057 from backstage/rugvip/convert-plugin

core-compat-api,catalog-react: add legacy converters for plugins and extensions

plugins/catalog-react/api-report-alpha.md

@@ -7,6 +7,7 @@
 
 import { AnyExtensionInputMap } from '@backstage/frontend-plugin-api';
 import { AnyRouteRefParams } from '@backstage/frontend-plugin-api';
+import { ComponentType } from 'react';
 import { ConfigurableExtensionDataRef } from '@backstage/frontend-plugin-api';
 import { Entity } from '@backstage/catalog-model';
 import { ExtensionBlueprint } from '@backstage/frontend-plugin-api';
@@ -95,6 +96,30 @@ export const catalogReactTranslationRef: TranslationRef<
   }
 >;
 
+// @alpha (undocumented)
+export function convertLegacyEntityCardExtension(
+  LegacyExtension: ComponentType<{}>,
+  overrides?: {
+    name?: string;
+    filter?:
+      | typeof EntityCardBlueprint.dataRefs.filterFunction.T
+      | typeof EntityCardBlueprint.dataRefs.filterExpression.T;
+  },
+): ExtensionDefinition<any>;
+
+// @alpha (undocumented)
+export function convertLegacyEntityContentExtension(
+  LegacyExtension: ComponentType<{}>,
+  overrides?: {
+    name?: string;
+    filter?:
+      | typeof EntityContentBlueprint.dataRefs.filterFunction.T
+      | typeof EntityContentBlueprint.dataRefs.filterExpression.T;
+    defaultPath?: string;
+    defaultTitle?: string;
+  },
+): ExtensionDefinition<any>;
+
 // @alpha @deprecated (undocumented)
 export function createEntityCardExtension<
   TConfig extends {

plugins/catalog-react/package.json

@@ -59,6 +59,7 @@
   "dependencies": {
     "@backstage/catalog-client": "workspace:^",
     "@backstage/catalog-model": "workspace:^",
+    "@backstage/core-compat-api": "workspace:^",
     "@backstage/core-components": "workspace:^",
     "@backstage/core-plugin-api": "workspace:^",
     "@backstage/errors": "workspace:^",

plugins/catalog-react/src/alpha/converters/convertLegacyEntityCardExtension.test.tsx

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2024 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 {
+  createPlugin as createLegacyPlugin,
+  createRouteRef as createLegacyRouteRef,
+  createRoutableExtension,
+} from '@backstage/core-plugin-api';
+import {
+  createExtensionTester,
+  renderInTestApp,
+} from '@backstage/frontend-test-utils';
+import { screen } from '@testing-library/react';
+import React from 'react';
+import { convertLegacyEntityCardExtension } from './convertLegacyEntityCardExtension';
+import { convertLegacyRouteRef } from '@backstage/core-compat-api';
+import { EntityContentBlueprint } from '../blueprints';
+
+const routeRef = createLegacyRouteRef({ id: 'test' });
+const legacyPlugin = createLegacyPlugin({
+  id: 'test',
+  routes: {
+    test: routeRef,
+  },
+});
+
+describe('convertLegacyEntityCardExtension', () => {
+  it('should convert an entity card extension', async () => {
+    const LegacyExtension = legacyPlugin.provide(
+      createRoutableExtension({
+        name: 'EntityExampleCard',
+        mountPoint: routeRef,
+        component: async () => () => <div>Hello</div>,
+      }),
+    );
+
+    const converted = convertLegacyEntityCardExtension(LegacyExtension);
+    expect(converted.kind).toBe('entity-card');
+    expect(converted.namespace).toBe(undefined);
+    expect(converted.name).toBe('example');
+
+    const tester = createExtensionTester(converted);
+
+    await renderInTestApp(tester.reactElement(), {
+      mountedRoutes: {
+        '/': convertLegacyRouteRef(routeRef),
+      },
+    });
+
+    await expect(screen.findByText('Hello')).resolves.toBeInTheDocument();
+
+    expect(tester.get(EntityContentBlueprint.dataRefs.filterExpression)).toBe(
+      undefined,
+    );
+    expect(tester.get(EntityContentBlueprint.dataRefs.filterFunction)).toBe(
+      undefined,
+    );
+  });
+
+  it('should convert an entity card extension with overrides', async () => {
+    const LegacyExtension = legacyPlugin.provide(
+      createRoutableExtension({
+        name: 'EntityExampleCard',
+        mountPoint: routeRef,
+        component: async () => () => <div>Hello</div>,
+      }),
+    );
+
+    const converted = convertLegacyEntityCardExtension(LegacyExtension, {
+      name: 'other',
+      filter: 'my-filter',
+    });
+    expect(converted.kind).toBe('entity-card');
+    expect(converted.namespace).toBe(undefined);
+    expect(converted.name).toBe('other');
+
+    const tester = createExtensionTester(converted);
+
+    await renderInTestApp(tester.reactElement(), {
+      mountedRoutes: {
+        '/': convertLegacyRouteRef(routeRef),
+      },
+    });
+
+    await expect(screen.findByText('Hello')).resolves.toBeInTheDocument();
+
+    expect(tester.get(EntityContentBlueprint.dataRefs.filterExpression)).toBe(
+      'my-filter',
+    );
+    expect(tester.get(EntityContentBlueprint.dataRefs.filterFunction)).toBe(
+      undefined,
+    );
+  });
+
+  it('should support various naming patterns for entity card extensions', async () => {
+    const withName = (name: string) => {
+      const converted = convertLegacyEntityCardExtension(
+        legacyPlugin.provide(
+          createRoutableExtension({
+            name,
+            mountPoint: routeRef,
+            component: async () => () => <div>Hello</div>,
+          }),
+        ),
+      );
+      return converted.name;
+    };
+
+    expect(withName('EntityTestCard')).toBe(undefined);
+    expect(withName('EntityTestTrimCard')).toBe('trim');
+    expect(withName('EntityTeStTrimCard')).toBe('trim');
+    expect(withName('EntityExampleCard')).toBe('example');
+    expect(withName('EntityExAmpleCard')).toBe('ex-ample');
+    expect(withName('ExampleCard')).toBe('example-card');
+  });
+});

plugins/catalog-react/src/alpha/converters/convertLegacyEntityCardExtension.tsx

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2024 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 { compatWrapper } from '@backstage/core-compat-api';
+import { BackstagePlugin, getComponentData } from '@backstage/core-plugin-api';
+import { ExtensionDefinition } from '@backstage/frontend-plugin-api';
+import React, { ComponentType } from 'react';
+import { EntityCardBlueprint } from '../blueprints';
+import kebabCase from 'lodash/kebabCase';
+
+/** @alpha */
+export function convertLegacyEntityCardExtension(
+  LegacyExtension: ComponentType<{}>,
+  overrides?: {
+    name?: string;
+    filter?:
+      | typeof EntityCardBlueprint.dataRefs.filterFunction.T
+      | typeof EntityCardBlueprint.dataRefs.filterExpression.T;
+  },
+): ExtensionDefinition<any> {
+  const element = <LegacyExtension />;
+
+  const extName = getComponentData<string>(element, 'core.extensionName');
+  if (!extName) {
+    throw new Error('Extension has no name');
+  }
+
+  const plugin = getComponentData<BackstagePlugin>(element, 'core.plugin');
+  const pluginId = plugin?.getId();
+
+  const match = extName.match(/^Entity(.*)Card$/);
+  const infix = match?.[1] ?? extName;
+
+  let name: string | undefined = infix;
+  if (
+    pluginId &&
+    name
+      .toLocaleLowerCase('en-US')
+      .startsWith(pluginId.toLocaleLowerCase('en-US'))
+  ) {
+    name = name.slice(pluginId.length);
+    if (!name) {
+      name = undefined;
+    }
+  }
+  name = name && kebabCase(name);
+
+  return EntityCardBlueprint.make({
+    name: overrides?.name ?? name,
+    params: {
+      filter: overrides?.filter,
+      loader: async () => compatWrapper(element),
+    },
+  });
+}

plugins/catalog-react/src/alpha/converters/convertLegacyEntityContentExtension.test.tsx

@@ -0,0 +1,136 @@
+/*
+ * Copyright 2024 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 {
+  createPlugin as createLegacyPlugin,
+  createRouteRef as createLegacyRouteRef,
+  createRoutableExtension,
+} from '@backstage/core-plugin-api';
+import { coreExtensionData } from '@backstage/frontend-plugin-api';
+import {
+  createExtensionTester,
+  renderInTestApp,
+} from '@backstage/frontend-test-utils';
+import { screen } from '@testing-library/react';
+import React from 'react';
+import { convertLegacyEntityContentExtension } from './convertLegacyEntityContentExtension';
+import { convertLegacyRouteRef } from '@backstage/core-compat-api';
+import { EntityContentBlueprint } from '../blueprints';
+
+const routeRef = createLegacyRouteRef({ id: 'test' });
+const legacyPlugin = createLegacyPlugin({
+  id: 'test',
+  routes: {
+    test: routeRef,
+  },
+});
+
+describe('convertLegacyEntityContentExtension', () => {
+  it('should convert an entity content extension', async () => {
+    const LegacyExtension = legacyPlugin.provide(
+      createRoutableExtension({
+        name: 'EntityExampleContent',
+        mountPoint: routeRef,
+        component: async () => () => <div>Hello</div>,
+      }),
+    );
+
+    const converted = convertLegacyEntityContentExtension(LegacyExtension);
+    expect(converted.kind).toBe('entity-content');
+    expect(converted.namespace).toBe(undefined);
+    expect(converted.name).toBe('example');
+
+    const tester = createExtensionTester(converted);
+
+    await renderInTestApp(tester.reactElement(), {
+      mountedRoutes: {
+        '/': convertLegacyRouteRef(routeRef),
+      },
+    });
+
+    await expect(screen.findByText('Hello')).resolves.toBeInTheDocument();
+
+    expect(tester.get(coreExtensionData.routePath)).toBe('/example');
+    expect(tester.get(coreExtensionData.routeRef)).toBe(routeRef);
+    expect(tester.get(EntityContentBlueprint.dataRefs.filterExpression)).toBe(
+      undefined,
+    );
+    expect(tester.get(EntityContentBlueprint.dataRefs.filterFunction)).toBe(
+      undefined,
+    );
+  });
+
+  it('should convert an entity content extension with overrides', async () => {
+    const LegacyExtension = legacyPlugin.provide(
+      createRoutableExtension({
+        name: 'EntityExampleContent',
+        mountPoint: routeRef,
+        component: async () => () => <div>Hello</div>,
+      }),
+    );
+
+    const converted = convertLegacyEntityContentExtension(LegacyExtension, {
+      name: 'other',
+      defaultPath: '/other',
+      defaultTitle: 'Other',
+      filter: 'my-filter',
+    });
+    expect(converted.kind).toBe('entity-content');
+    expect(converted.namespace).toBe(undefined);
+    expect(converted.name).toBe('other');
+
+    const tester = createExtensionTester(converted);
+
+    await renderInTestApp(tester.reactElement(), {
+      mountedRoutes: {
+        '/': convertLegacyRouteRef(routeRef),
+      },
+    });
+
+    await expect(screen.findByText('Hello')).resolves.toBeInTheDocument();
+
+    expect(tester.get(coreExtensionData.routePath)).toBe('/other');
+    expect(tester.get(coreExtensionData.routeRef)).toBe(routeRef);
+    expect(tester.get(EntityContentBlueprint.dataRefs.filterExpression)).toBe(
+      'my-filter',
+    );
+    expect(tester.get(EntityContentBlueprint.dataRefs.filterFunction)).toBe(
+      undefined,
+    );
+  });
+
+  it('should support various naming patterns for entity content extensions', async () => {
+    const withName = (name: string) => {
+      const converted = convertLegacyEntityContentExtension(
+        legacyPlugin.provide(
+          createRoutableExtension({
+            name,
+            mountPoint: routeRef,
+            component: async () => () => <div>Hello</div>,
+          }),
+        ),
+      );
+      return converted.name;
+    };
+
+    expect(withName('EntityTestContent')).toBe(undefined);
+    expect(withName('EntityTestTrimContent')).toBe('trim');
+    expect(withName('EntityTeStTrimContent')).toBe('trim');
+    expect(withName('EntityExampleContent')).toBe('example');
+    expect(withName('EntityExAmpleContent')).toBe('ex-ample');
+    expect(withName('ExampleContent')).toBe('example-content');
+  });
+});

plugins/catalog-react/src/alpha/converters/convertLegacyEntityContentExtension.tsx

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2024 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 {
+  compatWrapper,
+  convertLegacyRouteRef,
+} from '@backstage/core-compat-api';
+import {
+  BackstagePlugin,
+  getComponentData,
+  RouteRef as LegacyRouteRef,
+} from '@backstage/core-plugin-api';
+import { ExtensionDefinition } from '@backstage/frontend-plugin-api';
+import kebabCase from 'lodash/kebabCase';
+import startCase from 'lodash/startCase';
+import React, { ComponentType } from 'react';
+import { EntityContentBlueprint } from '../blueprints';
+
+/** @alpha */
+export function convertLegacyEntityContentExtension(
+  LegacyExtension: ComponentType<{}>,
+  overrides?: {
+    name?: string;
+    filter?:
+      | typeof EntityContentBlueprint.dataRefs.filterFunction.T
+      | typeof EntityContentBlueprint.dataRefs.filterExpression.T;
+    defaultPath?: string;
+    defaultTitle?: string;
+  },
+): ExtensionDefinition<any> {
+  const element = <LegacyExtension />;
+
+  const extName = getComponentData<string>(element, 'core.extensionName');
+  if (!extName) {
+    throw new Error('Extension has no name');
+  }
+
+  const mountPoint = getComponentData<LegacyRouteRef>(
+    element,
+    'core.mountPoint',
+  );
+
+  const plugin = getComponentData<BackstagePlugin>(element, 'core.plugin');
+  const pluginId = plugin?.getId();
+
+  const match = extName.match(/^Entity(.*)Content$/);
+  const infix = match?.[1] ?? extName;
+
+  let name: string | undefined = infix;
+  if (
+    pluginId &&
+    name
+      .toLocaleLowerCase('en-US')
+      .startsWith(pluginId.toLocaleLowerCase('en-US'))
+  ) {
+    name = name.slice(pluginId.length);
+    if (!name) {
+      name = undefined;
+    }
+  }
+  name = name && kebabCase(name);
+
+  return EntityContentBlueprint.make({
+    name: overrides?.name ?? name,
+    params: {
+      filter: overrides?.filter,
+      defaultPath: overrides?.defaultPath ?? `/${kebabCase(infix)}`,
+      defaultTitle: overrides?.defaultTitle ?? startCase(infix),
+      routeRef: mountPoint && convertLegacyRouteRef(mountPoint),
+      loader: async () => compatWrapper(element),
+    },
+  });
+}

plugins/catalog-react/src/alpha/converters/index.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2024 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.
+ */
+
+export { convertLegacyEntityCardExtension } from './convertLegacyEntityCardExtension';
+export { convertLegacyEntityContentExtension } from './convertLegacyEntityContentExtension';

plugins/catalog-react/src/alpha/index.ts

@@ -13,5 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 export * from './blueprints';
 export * from './extensions';
+export * from './converters';