@backstage/core-app-api 1.0.5 → 1.1.0-next.2

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @backstage/core-app-api
 
+## 1.1.0-next.2
+
+### Patch Changes
+
+- f9ec4e46e3: When using React Router v6 stable, it is now possible for components within the `Route` element tree to have `path` props, although they will be ignored.
+- 667d917488: Updated dependency `msw` to `^0.47.0`.
+- 87ec2ba4d6: Updated dependency `msw` to `^0.46.0`.
+- e9d40ebf54: If you'd like to send analytics events to multiple implementations, you may now
+  do so using the `MultipleAnalyticsApi` implementation provided by this package.
+
+  ```tsx
+  import { MultipleAnalyticsApi } from '@backstage/core-app-api';
+  import {
+    analyticsApiRef,
+    configApiRef,
+    storageApiRef,
+    identityApiRef,
+  } from '@internal/backstage/core-plugin-api';
+  import { CustomAnalyticsApi } from '@internal/analytics';
+  import { VendorAnalyticsApi } from '@vendor/analytics';
+
+  createApiFactory({
+    api: analyticsApiRef,
+    deps: { configApi: configApiRef, identityApi: identityApiRef, storageApi: storageApiRef },
+    factory: ({ configApi, identityApi, storageApi }) =>
+      MultipleAnalyticsApi.fromApis([
+        VendorAnalyticsApi.fromConfig(configApi, { identityApi }),
+        CustomAnalyticsApi.fromConfig(configApi, { identityApi, storageApi }),
+      ]),
+  }),
+  ```
+
+- Updated dependencies
+  - @backstage/core-plugin-api@1.0.6-next.2
+
+## 1.1.0-next.1
+
+### Minor Changes
+
+- a448fea691: Updated the routing system to be compatible with React Router v6 stable.
+
+### Patch Changes
+
+- 817f3196f6: Updated React Router dependencies to be peer dependencies.
+- 70299c99d5: Updated `FlatRoutes` to be compatible with React Router v6 stable.
+- Updated dependencies
+  - @backstage/core-plugin-api@1.0.6-next.1
+
+## 1.0.6-next.0
+
+### Patch Changes
+
+- 744fea158b: Added `getSystemIcons()` function to the `AppContext` available through `useApp` that will pull a list of all the icons that have been registered in the App.
+- bf5e9030eb: Updated dependency `msw` to `^0.45.0`.
+- Updated dependencies
+  - @backstage/core-plugin-api@1.0.6-next.0
+
 ## 1.0.5
 
 ### Patch Changes

package/dist/index.d.ts

@@ -276,6 +276,49 @@ declare class AlertApiForwarder implements AlertApi {
     alert$(): Observable<AlertMessage>;
 }
 
+/**
+ * An implementation of the AnalyticsApi that can be used to forward analytics
+ * events to multiple concrete implementations.
+ *
+ * @public
+ *
+ * @example
+ *
+ * ```jsx
+ * createApiFactory({
+ *   api: analyticsApiRef,
+ *   deps: { configApi: configApiRef, identityApi: identityApiRef, storageApi: storageApiRef },
+ *   factory: ({ configApi, identityApi, storageApi }) =>
+ *     MultipleAnalyticsApi.fromApis([
+ *       VendorAnalyticsApi.fromConfig(configApi, { identityApi }),
+ *       CustomAnalyticsApi.fromConfig(configApi, { identityApi, storageApi }),
+ *     ]),
+ * });
+ * ```
+ */
+declare class MultipleAnalyticsApi implements AnalyticsApi {
+    private readonly actualApis;
+    private constructor();
+    /**
+     * Create an AnalyticsApi implementation from an array of concrete
+     * implementations.
+     *
+     * @example
+     *
+     * ```jsx
+     * MultipleAnalyticsApi.fromApis([
+     *   SomeAnalyticsApi.fromConfig(configApi),
+     *   new CustomAnalyticsApi(),
+     * ]);
+     * ```
+     */
+    static fromApis(actualApis: AnalyticsApi[]): MultipleAnalyticsApi;
+    /**
+     * Forward the event to all configured analytics API implementations.
+     */
+    captureEvent(event: AnalyticsEvent): void;
+}
+
 /**
  * Base implementation for the AnalyticsApi that does nothing.
  *
@@ -778,6 +821,10 @@ declare type AppContext = {
      * Get a common or custom icon for this app.
      */
     getSystemIcon(key: string): IconComponent | undefined;
+    /**
+     * Get a list of common and custom icons for this app.
+     */
+    getSystemIcons(): Record<string, IconComponent>;
     /**
      * Get the components registered for various purposes in the app.
      */
@@ -855,4 +902,4 @@ declare type FeatureFlaggedProps = {
  */
 declare const FeatureFlagged: (props: FeatureFlaggedProps) => JSX.Element;
 
-export { AlertApiForwarder, ApiFactoryHolder, ApiFactoryRegistry, ApiFactoryScope, ApiProvider, ApiProviderProps, ApiResolver, AppComponents, AppConfigLoader, AppContext, AppIcons, AppOptions, AppRouteBinder, AppThemeSelector, AtlassianAuth, AuthApiCreateOptions, BackstageApp, BitbucketAuth, BitbucketSession, BootErrorPageProps, ErrorAlerter, ErrorApiForwarder, ErrorBoundaryFallbackProps, FeatureFlagged, FeatureFlaggedProps, FetchMiddleware, FetchMiddlewares, FlatRoutes, FlatRoutesProps, GithubAuth, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, NoOpAnalyticsApi, OAuth2, OAuth2CreateOptions, OAuth2Session, OAuthApiCreateOptions, OAuthRequestManager, OktaAuth, OneLoginAuth, OneLoginAuthCreateOptions, SamlAuth, SignInPageProps, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createFetchApi, createSpecializedApp, defaultConfigLoader };
+export { AlertApiForwarder, ApiFactoryHolder, ApiFactoryRegistry, ApiFactoryScope, ApiProvider, ApiProviderProps, ApiResolver, AppComponents, AppConfigLoader, AppContext, AppIcons, AppOptions, AppRouteBinder, AppThemeSelector, AtlassianAuth, AuthApiCreateOptions, BackstageApp, BitbucketAuth, BitbucketSession, BootErrorPageProps, ErrorAlerter, ErrorApiForwarder, ErrorBoundaryFallbackProps, FeatureFlagged, FeatureFlaggedProps, FetchMiddleware, FetchMiddlewares, FlatRoutes, FlatRoutesProps, GithubAuth, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, MultipleAnalyticsApi, NoOpAnalyticsApi, OAuth2, OAuth2CreateOptions, OAuth2Session, OAuthApiCreateOptions, OAuthRequestManager, OktaAuth, OneLoginAuth, OneLoginAuthCreateOptions, SamlAuth, SignInPageProps, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createFetchApi, createSpecializedApp, defaultConfigLoader };

package/dist/index.esm.js

@@ -6,7 +6,7 @@ import { SessionState, FeatureFlagState, getComponentData, attachComponentData,
 import { z } from 'zod';
 import { ConfigReader } from '@backstage/config';
 export { ConfigReader } from '@backstage/config';
-import { matchRoutes, generatePath, useLocation, Routes, Route, useRoutes } from 'react-router-dom';
+import { matchRoutes, generatePath, useLocation, createRoutesFromChildren, Route, Routes, useRoutes } from 'react-router-dom';
 import useAsync from 'react-use/lib/useAsync';
 import useObservable from 'react-use/lib/useObservable';
 
@@ -1172,6 +1172,23 @@ class AlertApiForwarder {
   }
 }
 
+class MultipleAnalyticsApi {
+  constructor(actualApis) {
+    this.actualApis = actualApis;
+  }
+  static fromApis(actualApis) {
+    return new MultipleAnalyticsApi(actualApis);
+  }
+  captureEvent(event) {
+    this.actualApis.forEach((analyticsApi) => {
+      try {
+        analyticsApi.captureEvent(event);
+      } catch {
+      }
+    });
+  }
+}
+
 class NoOpAnalyticsApi {
   captureEvent(_event) {
   }
@@ -1745,10 +1762,137 @@ attachComponentData(FeatureFlagged, "core.featureFlagged", true);
 
 const MATCH_ALL_ROUTE = {
   caseSensitive: false,
-  path: "/*",
+  path: "*",
   element: "match-all",
   routeRefs: /* @__PURE__ */ new Set()
 };
+function stringifyNode(node) {
+  var _a, _b;
+  const anyNode = node;
+  if (anyNode == null ? void 0 : anyNode.type) {
+    return (_b = (_a = anyNode.type.displayName) != null ? _a : anyNode.type.name) != null ? _b : String(anyNode.type);
+  }
+  return String(anyNode);
+}
+function collectSubTree(node, entries = new Array()) {
+  Children.forEach(node, (element) => {
+    if (!isValidElement(element)) {
+      return;
+    }
+    const routeRef = getComponentData(element, "core.mountPoint");
+    if (routeRef) {
+      const plugin = getComponentData(element, "core.plugin");
+      entries.push({ routeRef, plugin });
+    }
+    collectSubTree(element.props.children, entries);
+  });
+  return entries;
+}
+const routingV2Collector = createCollector(
+  () => ({
+    paths: /* @__PURE__ */ new Map(),
+    parents: /* @__PURE__ */ new Map(),
+    objects: new Array()
+  }),
+  (acc, node, parent, ctx) => {
+    var _a, _b, _c, _d, _e, _f;
+    if (ctx == null ? void 0 : ctx.isElementAncestor) {
+      return ctx;
+    }
+    if ((parent == null ? void 0 : parent.props.element) === node) {
+      return { ...ctx, isElementAncestor: true };
+    }
+    const pathProp = (_a = node.props) == null ? void 0 : _a.path;
+    const mountPoint = getComponentData(node, "core.mountPoint");
+    if (mountPoint && pathProp) {
+      throw new Error(
+        `Path property may not be set directly on a routable extension "${stringifyNode(
+          node
+        )}"`
+      );
+    }
+    const parentChildren = (_c = (_b = ctx == null ? void 0 : ctx.obj) == null ? void 0 : _b.children) != null ? _c : acc.objects;
+    if (pathProp !== void 0) {
+      if (typeof pathProp !== "string") {
+        throw new Error(
+          `Element path must be a string at "${stringifyNode(node)}"`
+        );
+      }
+      const path = pathProp.startsWith("/") ? pathProp.slice(1) : pathProp;
+      const elementProp = node.props.element;
+      if (getComponentData(node, "core.gatherMountPoints")) {
+        if (elementProp) {
+          throw new Error(
+            `Mount point gatherers may not have an element prop "${stringifyNode(
+              node
+            )}"`
+          );
+        }
+        const newObj = {
+          path,
+          element: "gathered",
+          routeRefs: /* @__PURE__ */ new Set(),
+          caseSensitive: Boolean((_d = node.props) == null ? void 0 : _d.caseSensitive),
+          children: [MATCH_ALL_ROUTE],
+          plugin: void 0
+        };
+        parentChildren.push(newObj);
+        return {
+          obj: newObj,
+          gatherPath: path,
+          routeRef: ctx == null ? void 0 : ctx.routeRef,
+          gatherRouteRef: ctx == null ? void 0 : ctx.routeRef
+        };
+      }
+      if (elementProp) {
+        const [extension, ...others] = collectSubTree(elementProp);
+        if (others.length > 0) {
+          throw new Error(
+            `Route element with path "${pathProp}" may not contain multiple routable extensions`
+          );
+        }
+        if (!extension) {
+          return ctx;
+        }
+        const { routeRef, plugin } = extension;
+        const newObj = {
+          path,
+          element: "mounted",
+          routeRefs: /* @__PURE__ */ new Set([routeRef]),
+          caseSensitive: Boolean((_e = node.props) == null ? void 0 : _e.caseSensitive),
+          children: [MATCH_ALL_ROUTE],
+          plugin
+        };
+        parentChildren.push(newObj);
+        acc.paths.set(routeRef, path);
+        acc.parents.set(routeRef, ctx == null ? void 0 : ctx.routeRef);
+        return {
+          obj: newObj,
+          routeRef: routeRef != null ? routeRef : ctx == null ? void 0 : ctx.routeRef,
+          gatherPath: path,
+          gatherRouteRef: ctx == null ? void 0 : ctx.gatherRouteRef
+        };
+      }
+    }
+    if (mountPoint) {
+      if (!(ctx == null ? void 0 : ctx.gatherPath)) {
+        throw new Error(
+          `Routable extension "${stringifyNode(
+            node
+          )}" with mount point "${mountPoint}" must be assigned a path`
+        );
+      }
+      (_f = ctx == null ? void 0 : ctx.obj) == null ? void 0 : _f.routeRefs.add(mountPoint);
+      acc.paths.set(mountPoint, ctx.gatherPath);
+      acc.parents.set(mountPoint, ctx == null ? void 0 : ctx.gatherRouteRef);
+      return {
+        ...ctx,
+        routeRef: mountPoint
+      };
+    }
+    return ctx;
+  }
+);
 const routingV1Collector = createCollector(
   () => ({
     paths: /* @__PURE__ */ new Map(),
@@ -1880,6 +2024,7 @@ function joinPaths(...paths) {
   }
   return normalized;
 }
+
 function resolveTargetRef(anyRouteRef, routePaths, routeBindings) {
   let targetRef;
   let subRoutePath = "";
@@ -1914,7 +2059,7 @@ function resolveTargetRef(anyRouteRef, routePaths, routeBindings) {
     return [void 0, ""];
   }
   const resolvedPath = routePaths.get(targetRef);
-  if (!resolvedPath) {
+  if (resolvedPath === void 0) {
     return [void 0, ""];
   }
   const targetPath = joinPaths(resolvedPath, subRoutePath);
@@ -1938,21 +2083,19 @@ function resolveBasePath(targetRef, sourceLocation, routePaths, routeParents, ro
     matchIndex -= 1;
   }
   const parentPath = matchIndex === -1 ? "" : match[matchIndex].pathname;
-  const diffPath = joinPaths(
-    ...refDiffList.slice(0, -1).map((ref) => {
-      const path = routePaths.get(ref);
-      if (!path) {
-        throw new Error(`No path for ${ref}`);
-      }
-      if (path.includes(":")) {
-        throw new Error(
-          `Cannot route to ${targetRef} with parent ${ref} as it has parameters`
-        );
-      }
-      return path;
-    })
-  );
-  return parentPath + diffPath;
+  const diffPaths = refDiffList.slice(0, -1).map((ref) => {
+    const path = routePaths.get(ref);
+    if (path === void 0) {
+      throw new Error(`No path for ${ref}`);
+    }
+    if (path.includes(":")) {
+      throw new Error(
+        `Cannot route to ${targetRef} with parent ${ref} as it has parameters`
+      );
+    }
+    return path;
+  });
+  return `${joinPaths(parentPath, ...diffPaths)}/`;
 }
 class RouteResolver {
   constructor(routePaths, routeParents, routeObjects, routeBindings, appBasePath) {
@@ -1990,7 +2133,7 @@ class RouteResolver {
       this.routeObjects
     );
     const routeFunc = (...[params]) => {
-      return basePath + generatePath(targetPath, params);
+      return joinPaths(basePath, generatePath(targetPath, params));
     };
     return routeFunc;
   }
@@ -2088,10 +2231,10 @@ function validateRouteParameters(routePaths, routeParents) {
     let fullPath = "";
     while (currentRouteRef) {
       const path = routePaths.get(currentRouteRef);
-      if (!path) {
+      if (path === void 0) {
         throw new Error(`No path for ${currentRouteRef}`);
       }
-      fullPath = `${path}${fullPath}`;
+      fullPath = joinPaths(path, fullPath);
       currentRouteRef = routeParents.get(currentRouteRef);
     }
     const params = fullPath.match(/:(\w+)/g);
@@ -2360,6 +2503,14 @@ function resolveRouteBindings(bindRoutes) {
   return result;
 }
 
+function isReactRouterBeta() {
+  const [obj] = createRoutesFromChildren(/* @__PURE__ */ React.createElement(Route, {
+    index: true,
+    element: /* @__PURE__ */ React.createElement("div", null)
+  }));
+  return !obj.index;
+}
+
 const InternalAppContext = createContext({ routeObjects: [] });
 function getBasePath(configApi) {
   var _a;
@@ -2406,6 +2557,9 @@ class AppContextImpl {
   getSystemIcon(key) {
     return this.app.getSystemIcon(key);
   }
+  getSystemIcons() {
+    return this.app.getSystemIcons();
+  }
   getComponents() {
     return this.app.getComponents();
   }
@@ -2430,6 +2584,9 @@ class AppManager {
   getSystemIcon(key) {
     return this.icons[key];
   }
+  getSystemIcons() {
+    return this.icons;
+  }
   getComponents() {
     return this.components;
   }
@@ -2446,7 +2603,7 @@ class AppManager {
           root: children,
           discoverers: [childDiscoverer, routeElementDiscoverer],
           collectors: {
-            routing: routingV1Collector,
+            routing: isReactRouterBeta() ? routingV1Collector : routingV2Collector,
             collectedPlugins: pluginCollector,
             featureFlags: featureFlagCollector
           }
@@ -2674,9 +2831,11 @@ function createSpecializedApp(options) {
   return new AppManager(options);
 }
 
+let warned = false;
 const FlatRoutes = (props) => {
   const app = useApp();
   const { NotFoundErrorPage } = app.getComponents();
+  const isBeta = useMemo(() => isReactRouterBeta(), []);
   const routes = useElementFilter(
     props.children,
     (elements) => elements.getElements().flatMap((child) => {
@@ -2686,29 +2845,39 @@ const FlatRoutes = (props) => {
         return [];
       }
       path = (_a = path == null ? void 0 : path.replace(/\/\*$/, "")) != null ? _a : "/";
+      let element = isBeta ? child : child.props.element;
+      if (!isBeta && !element) {
+        element = child;
+        if (!warned && process.env.NODE_ENV !== "test") {
+          console.warn(
+            "DEPRECATION WARNING: All elements within <FlatRoutes> must be of type <Route> with an element prop. Existing usages of <Navigate key=[path] to=[to] /> should be replaced with <Route path=[path] element={<Navigate to=[to] />} />."
+          );
+          warned = true;
+        }
+      }
       return [
         {
           path,
-          element: child,
+          element,
           children: child.props.children ? [
             {
-              path: path === "/" ? "/" : "/*",
+              path: path === "/" ? "/" : "*",
               element: child.props.children
             }
           ] : void 0
         }
       ];
-    }).sort((a, b) => b.path.localeCompare(a.path)).map((obj) => {
-      obj.path = obj.path === "/" ? "/" : `${obj.path}/*`;
-      return obj;
-    })
+    }).sort((a, b) => b.path.localeCompare(a.path)).map((obj) => ({ ...obj, path: obj.path === "/" ? "/" : `${obj.path}/*` }))
   );
-  routes.push({
-    element: /* @__PURE__ */ React.createElement(NotFoundErrorPage, null),
-    path: "/*"
-  });
-  return useRoutes(routes);
+  const withNotFound = [
+    ...routes,
+    {
+      path: "*",
+      element: /* @__PURE__ */ React.createElement(NotFoundErrorPage, null)
+    }
+  ];
+  return useRoutes(withNotFound);
 };
 
-export { AlertApiForwarder, ApiFactoryRegistry, ApiProvider, ApiResolver, AppThemeSelector, AtlassianAuth, BitbucketAuth, ErrorAlerter, ErrorApiForwarder, FeatureFlagged, FetchMiddlewares, FlatRoutes, GithubAuth, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, NoOpAnalyticsApi, OAuth2, OAuthRequestManager, OktaAuth, OneLoginAuth, SamlAuth, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createFetchApi, createSpecializedApp, defaultConfigLoader };
+export { AlertApiForwarder, ApiFactoryRegistry, ApiProvider, ApiResolver, AppThemeSelector, AtlassianAuth, BitbucketAuth, ErrorAlerter, ErrorApiForwarder, FeatureFlagged, FetchMiddlewares, FlatRoutes, GithubAuth, GitlabAuth, GoogleAuth, LocalStorageFeatureFlags, MicrosoftAuth, MultipleAnalyticsApi, NoOpAnalyticsApi, OAuth2, OAuthRequestManager, OktaAuth, OneLoginAuth, SamlAuth, UnhandledErrorForwarder, UrlPatternDiscovery, WebStorage, createFetchApi, createSpecializedApp, defaultConfigLoader };
 //# sourceMappingURL=index.esm.js.map