@backstage/core-plugin-api 1.7.0 → 1.8.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @backstage/core-plugin-api
 
+## 1.8.0-next.0
+
+### Minor Changes
+
+- 1e5b7d993a: `IconComponent` can now have a `fontSize` of `inherit`, which is useful for in-line icons.
+- cb6db75bc2: Introduced `AnyRouteRefParams` as a replacement for `AnyParams`, which is now deprecated.
+
+### Patch Changes
+
+- 6c2b872153: Add official support for React 18.
+- cb6db75bc2: Deprecated several types related to the routing system that are scheduled to be removed, as well as several fields on the route ref types themselves.
+- 68fc9dc60e: Added a new `/alpha` export `convertLegacyRouteRef`, which is a temporary utility to allow existing route refs to be used with the new experimental packages.
+- Updated dependencies
+  - @backstage/version-bridge@1.0.7-next.0
+  - @backstage/config@1.1.1
+  - @backstage/types@1.1.1
+
 ## 1.7.0
 
 ### Minor Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/core-plugin-api",
-  "version": "1.7.0",
+  "version": "1.8.0-next.0",
   "main": "../dist/alpha.esm.js",
   "module": "../dist/alpha.esm.js",
   "types": "../dist/alpha.d.ts"

package/dist/alpha.d.ts

@@ -1,5 +1,5 @@
 import { TranslationRef as TranslationRef$1, TranslationMessages as TranslationMessages$1 } from '@backstage/core-plugin-api/alpha';
-import { ApiRef } from '@backstage/core-plugin-api';
+import { ApiRef, AnyRouteRefParams as AnyRouteRefParams$1, RouteRef as RouteRef$1, SubRouteRef as SubRouteRef$1, ExternalRouteRef as ExternalRouteRef$1 } from '@backstage/core-plugin-api';
 import { Observable } from '@backstage/types';
 
 /**
@@ -391,4 +391,91 @@ declare const useTranslationRef: <TMessages extends {
     t: TranslationFunction<TMessages>;
 };
 
-export { AppLanguageApi, TranslationApi, TranslationFunction, TranslationMessages, TranslationMessagesOptions, TranslationRef, TranslationRefOptions, TranslationResource, TranslationResourceOptions, TranslationSnapshot, appLanguageApiRef, createTranslationMessages, createTranslationRef, createTranslationResource, translationApiRef, useTranslationRef };
+/**
+ * Catch-all type for route params.
+ *
+ * @public
+ */
+type AnyRouteRefParams = {
+    [param in string]: string;
+} | undefined;
+
+/**
+ * Absolute route reference.
+ *
+ * @remarks
+ *
+ * See {@link https://backstage.io/docs/plugins/composability#routing-system}.
+ *
+ * @public
+ */
+interface RouteRef<TParams extends AnyRouteRefParams = AnyRouteRefParams> {
+    readonly $$type: '@backstage/RouteRef';
+    readonly T: TParams;
+}
+
+/**
+ * Descriptor of a route relative to an absolute {@link RouteRef}.
+ *
+ * @remarks
+ *
+ * See {@link https://backstage.io/docs/plugins/composability#routing-system}.
+ *
+ * @public
+ */
+interface SubRouteRef<TParams extends AnyRouteRefParams = AnyRouteRefParams> {
+    readonly $$type: '@backstage/SubRouteRef';
+    readonly T: TParams;
+    readonly path: string;
+}
+
+/**
+ * Route descriptor, to be later bound to a concrete route by the app. Used to implement cross-plugin route references.
+ *
+ * @remarks
+ *
+ * See {@link https://backstage.io/docs/plugins/composability#routing-system}.
+ *
+ * @public
+ */
+interface ExternalRouteRef<TParams extends AnyRouteRefParams = AnyRouteRefParams, TOptional extends boolean = boolean> {
+    readonly $$type: '@backstage/ExternalRouteRef';
+    readonly T: TParams;
+    readonly optional: TOptional;
+}
+
+/** @ignore */
+type NewRouteRef<TParams extends AnyRouteRefParams$1 = AnyRouteRefParams$1> = RouteRef<TParams>;
+/** @ignore */
+type NewSubRouteRef<TParams extends AnyRouteRefParams$1 = AnyRouteRefParams$1> = SubRouteRef<TParams>;
+/** @ignore */
+type NewExternalRouteRef<TParams extends AnyRouteRefParams$1 = AnyRouteRefParams$1, TOptional extends boolean = boolean> = ExternalRouteRef<TParams, TOptional>;
+/**
+ * A temporary helper to convert a legacy route ref to the new system.
+ *
+ * @public
+ * @remarks
+ *
+ * In the future the legacy createRouteRef will instead create refs compatible with both systems.
+ */
+declare function convertLegacyRouteRef<TParams extends AnyRouteRefParams$1>(ref: RouteRef$1<TParams>): NewRouteRef<TParams>;
+/**
+ * A temporary helper to convert a legacy sub route ref to the new system.
+ *
+ * @public
+ * @remarks
+ *
+ * In the future the legacy createSubRouteRef will instead create refs compatible with both systems.
+ */
+declare function convertLegacyRouteRef<TParams extends AnyRouteRefParams$1>(ref: SubRouteRef$1<TParams>): NewSubRouteRef<TParams>;
+/**
+ * A temporary helper to convert a legacy external route ref to the new system.
+ *
+ * @public
+ * @remarks
+ *
+ * In the future the legacy createExternalRouteRef will instead create refs compatible with both systems.
+ */
+declare function convertLegacyRouteRef<TParams extends AnyRouteRefParams$1, TOptional extends boolean>(ref: ExternalRouteRef$1<TParams, TOptional>): NewExternalRouteRef<TParams, TOptional>;
+
+export { AppLanguageApi, TranslationApi, TranslationFunction, TranslationMessages, TranslationMessagesOptions, TranslationRef, TranslationRefOptions, TranslationResource, TranslationResourceOptions, TranslationSnapshot, appLanguageApiRef, convertLegacyRouteRef, createTranslationMessages, createTranslationRef, createTranslationResource, translationApiRef, useTranslationRef };

package/dist/alpha.esm.js

@@ -1,6 +1,7 @@
 import { useState, useMemo, useCallback, useEffect, useRef } from 'react';
-import { u as useApi, r as errorApiRef } from './esm/StorageApi-2de4f480.esm.js';
+import { u as useApi, s as errorApiRef, r as routeRefType } from './esm/types-08c0ee05.esm.js';
 import { createApiRef } from '@backstage/core-plugin-api';
+import 'react-router-dom';
 import '@backstage/version-bridge';
 
 function createTranslationMessages(options) {
@@ -31,61 +32,61 @@ function createTranslationResource(options) {
   };
 }
 
-var __defProp = Object.defineProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField = (obj, key, value) => {
-  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$3 = Object.defineProperty;
+var __defNormalProp$3 = (obj, key, value) => key in obj ? __defProp$3(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$3 = (obj, key, value) => {
+  __defNormalProp$3(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
-var __accessCheck = (obj, member, msg) => {
+var __accessCheck$2 = (obj, member, msg) => {
   if (!member.has(obj))
     throw TypeError("Cannot " + msg);
 };
-var __privateGet = (obj, member, getter) => {
-  __accessCheck(obj, member, "read from private field");
+var __privateGet$2 = (obj, member, getter) => {
+  __accessCheck$2(obj, member, "read from private field");
   return getter ? getter.call(obj) : member.get(obj);
 };
-var __privateAdd = (obj, member, value) => {
+var __privateAdd$2 = (obj, member, value) => {
   if (member.has(obj))
     throw TypeError("Cannot add the same private member more than once");
   member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 };
-var __privateSet = (obj, member, value, setter) => {
-  __accessCheck(obj, member, "write to private field");
+var __privateSet$2 = (obj, member, value, setter) => {
+  __accessCheck$2(obj, member, "write to private field");
   setter ? setter.call(obj, value) : member.set(obj, value);
   return value;
 };
-var _id, _messages, _resources;
+var _id$1, _messages, _resources;
 class TranslationRefImpl {
   constructor(options) {
-    __privateAdd(this, _id, void 0);
-    __privateAdd(this, _messages, void 0);
-    __privateAdd(this, _resources, void 0);
-    __publicField(this, "$$type", "@backstage/TranslationRef");
-    __publicField(this, "version", "v1");
-    __privateSet(this, _id, options.id);
-    __privateSet(this, _messages, options.messages);
+    __privateAdd$2(this, _id$1, void 0);
+    __privateAdd$2(this, _messages, void 0);
+    __privateAdd$2(this, _resources, void 0);
+    __publicField$3(this, "$$type", "@backstage/TranslationRef");
+    __publicField$3(this, "version", "v1");
+    __privateSet$2(this, _id$1, options.id);
+    __privateSet$2(this, _messages, options.messages);
   }
   get id() {
-    return __privateGet(this, _id);
+    return __privateGet$2(this, _id$1);
   }
   get T() {
     throw new Error("Not implemented");
   }
   getDefaultMessages() {
-    return __privateGet(this, _messages);
+    return __privateGet$2(this, _messages);
   }
   setDefaultResource(resources) {
-    __privateSet(this, _resources, resources);
+    __privateSet$2(this, _resources, resources);
   }
   getDefaultResource() {
-    return __privateGet(this, _resources);
+    return __privateGet$2(this, _resources);
   }
   toString() {
     return `TranslationRef{id=${this.id}}`;
   }
 }
-_id = new WeakMap();
+_id$1 = new WeakMap();
 _messages = new WeakMap();
 _resources = new WeakMap();
 function createTranslationRef(config) {
@@ -174,5 +175,313 @@ const useTranslationRef = (translationRef) => {
   return { t: snapshot.t };
 };
 
-export { appLanguageApiRef, createTranslationMessages, createTranslationRef, createTranslationResource, translationApiRef, useTranslationRef };
+const MESSAGE_MARKER = "eHgtF5hmbrXyiEvo";
+function describeParentCallSite(ErrorConstructor = Error) {
+  const { stack } = new ErrorConstructor(MESSAGE_MARKER);
+  if (!stack) {
+    return "<unknown>";
+  }
+  const startIndex = stack.includes(MESSAGE_MARKER) ? stack.indexOf("\n") + 1 : 0;
+  const secondEntryStart = stack.indexOf("\n", stack.indexOf("\n", startIndex) + 1) + 1;
+  const secondEntryEnd = stack.indexOf("\n", secondEntryStart);
+  const line = stack.substring(secondEntryStart, secondEntryEnd).trim();
+  if (!line) {
+    return "unknown";
+  }
+  if (line.includes("(")) {
+    return line.substring(line.indexOf("(") + 1, line.indexOf(")"));
+  }
+  if (line.includes("@")) {
+    return line.substring(line.indexOf("@") + 1);
+  }
+  return line;
+}
+
+var __defProp$2 = Object.defineProperty;
+var __defNormalProp$2 = (obj, key, value) => key in obj ? __defProp$2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$2 = (obj, key, value) => {
+  __defNormalProp$2(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+var __accessCheck$1 = (obj, member, msg) => {
+  if (!member.has(obj))
+    throw TypeError("Cannot " + msg);
+};
+var __privateGet$1 = (obj, member, getter) => {
+  __accessCheck$1(obj, member, "read from private field");
+  return getter ? getter.call(obj) : member.get(obj);
+};
+var __privateAdd$1 = (obj, member, value) => {
+  if (member.has(obj))
+    throw TypeError("Cannot add the same private member more than once");
+  member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+};
+var __privateSet$1 = (obj, member, value, setter) => {
+  __accessCheck$1(obj, member, "write to private field");
+  setter ? setter.call(obj, value) : member.set(obj, value);
+  return value;
+};
+var _id, _params$1, _creationSite, _name, name_get;
+function toInternalRouteRef(resource) {
+  const r = resource;
+  if (r.$$type !== "@backstage/RouteRef") {
+    throw new Error(`Invalid RouteRef, bad type '${r.$$type}'`);
+  }
+  return r;
+}
+class RouteRefImpl {
+  constructor(params = [], creationSite) {
+    this.params = params;
+    __privateAdd$1(this, _name);
+    __publicField$2(this, "$$type", "@backstage/RouteRef");
+    __publicField$2(this, "version", "v1");
+    __privateAdd$1(this, _id, void 0);
+    __privateAdd$1(this, _params$1, void 0);
+    __privateAdd$1(this, _creationSite, void 0);
+    __privateSet$1(this, _params$1, params);
+    __privateSet$1(this, _creationSite, creationSite);
+  }
+  getParams() {
+    return __privateGet$1(this, _params$1);
+  }
+  getDescription() {
+    if (__privateGet$1(this, _id)) {
+      return __privateGet$1(this, _id);
+    }
+    return `created at '${__privateGet$1(this, _creationSite)}'`;
+  }
+  setId(id) {
+    if (!id) {
+      throw new Error(`${__privateGet$1(this, _name, name_get)} id must be a non-empty string`);
+    }
+    if (__privateGet$1(this, _id)) {
+      throw new Error(
+        `${__privateGet$1(this, _name, name_get)} was referenced twice as both '${__privateGet$1(this, _id)}' and '${id}'`
+      );
+    }
+    __privateSet$1(this, _id, id);
+  }
+  toString() {
+    return `${__privateGet$1(this, _name, name_get)}{${this.getDescription()}}`;
+  }
+}
+_id = new WeakMap();
+_params$1 = new WeakMap();
+_creationSite = new WeakMap();
+_name = new WeakSet();
+name_get = function() {
+  return this.$$type.slice("@backstage/".length);
+};
+function createRouteRef(config) {
+  return new RouteRefImpl(
+    config == null ? void 0 : config.params,
+    describeParentCallSite()
+  );
+}
+
+var __defProp$1 = Object.defineProperty;
+var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$1 = (obj, key, value) => {
+  __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+var __accessCheck = (obj, member, msg) => {
+  if (!member.has(obj))
+    throw TypeError("Cannot " + msg);
+};
+var __privateGet = (obj, member, getter) => {
+  __accessCheck(obj, member, "read from private field");
+  return getter ? getter.call(obj) : member.get(obj);
+};
+var __privateAdd = (obj, member, value) => {
+  if (member.has(obj))
+    throw TypeError("Cannot add the same private member more than once");
+  member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+};
+var __privateSet = (obj, member, value, setter) => {
+  __accessCheck(obj, member, "write to private field");
+  setter ? setter.call(obj, value) : member.set(obj, value);
+  return value;
+};
+var _params, _parent;
+const PARAM_PATTERN = /^\w+$/;
+function toInternalSubRouteRef(resource) {
+  const r = resource;
+  if (r.$$type !== "@backstage/SubRouteRef") {
+    throw new Error(`Invalid SubRouteRef, bad type '${r.$$type}'`);
+  }
+  return r;
+}
+class SubRouteRefImpl {
+  constructor(path, params, parent) {
+    this.path = path;
+    __publicField$1(this, "$$type", "@backstage/SubRouteRef");
+    __publicField$1(this, "version", "v1");
+    __privateAdd(this, _params, void 0);
+    __privateAdd(this, _parent, void 0);
+    __privateSet(this, _params, params);
+    __privateSet(this, _parent, parent);
+  }
+  getParams() {
+    return __privateGet(this, _params);
+  }
+  getParent() {
+    return __privateGet(this, _parent);
+  }
+  getDescription() {
+    const parent = toInternalRouteRef(__privateGet(this, _parent));
+    return `at ${this.path} with parent ${parent.getDescription()}`;
+  }
+  toString() {
+    return `SubRouteRef{${this.getDescription()}}`;
+  }
+}
+_params = new WeakMap();
+_parent = new WeakMap();
+function createSubRouteRef(config) {
+  const { path, parent } = config;
+  const internalParent = toInternalRouteRef(parent);
+  const parentParams = internalParent.getParams();
+  const pathParams = path.split("/").filter((p) => p.startsWith(":")).map((p) => p.substring(1));
+  const params = [...parentParams, ...pathParams];
+  if (parentParams.some((p) => pathParams.includes(p))) {
+    throw new Error(
+      "SubRouteRef may not have params that overlap with its parent"
+    );
+  }
+  if (!path.startsWith("/")) {
+    throw new Error(`SubRouteRef path must start with '/', got '${path}'`);
+  }
+  if (path.endsWith("/")) {
+    throw new Error(`SubRouteRef path must not end with '/', got '${path}'`);
+  }
+  for (const param of pathParams) {
+    if (!PARAM_PATTERN.test(param)) {
+      throw new Error(`SubRouteRef path has invalid param, got '${param}'`);
+    }
+  }
+  const subRouteRef = new SubRouteRefImpl(
+    path,
+    params,
+    parent
+  );
+  return subRouteRef;
+}
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+function toInternalExternalRouteRef(resource) {
+  const r = resource;
+  if (r.$$type !== "@backstage/ExternalRouteRef") {
+    throw new Error(`Invalid ExternalRouteRef, bad type '${r.$$type}'`);
+  }
+  return r;
+}
+class ExternalRouteRefImpl extends RouteRefImpl {
+  constructor(optional, params = [], creationSite) {
+    super(params, creationSite);
+    this.optional = optional;
+    this.params = params;
+    __publicField(this, "$$type", "@backstage/ExternalRouteRef");
+  }
+}
+function createExternalRouteRef(options) {
+  return new ExternalRouteRefImpl(
+    Boolean(options == null ? void 0 : options.optional),
+    options == null ? void 0 : options.params,
+    describeParentCallSite()
+  );
+}
+
+function convertLegacyRouteRef(ref) {
+  if ("$$type" in ref) {
+    return ref;
+  }
+  const type = ref[routeRefType];
+  if (type === "absolute") {
+    const legacyRef = ref;
+    const newRef = toInternalRouteRef(
+      createRouteRef({
+        params: legacyRef.params
+      })
+    );
+    return Object.assign(legacyRef, {
+      $$type: "@backstage/RouteRef",
+      version: "v1",
+      T: newRef.T,
+      getParams() {
+        return newRef.getParams();
+      },
+      getDescription() {
+        return newRef.getDescription();
+      },
+      setId(id) {
+        newRef.setId(id);
+      },
+      toString() {
+        return newRef.toString();
+      }
+    });
+  }
+  if (type === "sub") {
+    const legacyRef = ref;
+    const newRef = toInternalSubRouteRef(
+      createSubRouteRef({
+        path: legacyRef.path,
+        parent: convertLegacyRouteRef(legacyRef.parent)
+      })
+    );
+    return Object.assign(legacyRef, {
+      $$type: "@backstage/SubRouteRef",
+      version: "v1",
+      T: newRef.T,
+      getParams() {
+        return newRef.getParams();
+      },
+      getParent() {
+        return newRef.getParent();
+      },
+      getDescription() {
+        return newRef.getDescription();
+      },
+      toString() {
+        return newRef.toString();
+      }
+    });
+  }
+  if (type === "external") {
+    const legacyRef = ref;
+    const newRef = toInternalExternalRouteRef(
+      createExternalRouteRef({
+        params: legacyRef.params,
+        optional: legacyRef.optional
+      })
+    );
+    return Object.assign(legacyRef, {
+      $$type: "@backstage/ExternalRouteRef",
+      version: "v1",
+      T: newRef.T,
+      optional: newRef.optional,
+      getParams() {
+        return newRef.getParams();
+      },
+      getDescription() {
+        return newRef.getDescription();
+      },
+      setId(id) {
+        newRef.setId(id);
+      },
+      toString() {
+        return newRef.toString();
+      }
+    });
+  }
+  throw new Error(`Failed to convert legacy route ref, unknown type '${type}'`);
+}
+
+export { appLanguageApiRef, convertLegacyRouteRef, createTranslationMessages, createTranslationRef, createTranslationResource, translationApiRef, useTranslationRef };
 //# sourceMappingURL=alpha.esm.js.map