@backstage/core-plugin-api 1.8.0 → 1.8.1-next.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @backstage/core-plugin-api
 
+## 1.8.1-next.1
+
+### Patch Changes
+
+- 0c93dc37b2: The `createTranslationRef` function from the `/alpha` subpath can now also accept a nested object structure of default translation messages, which will be flatted using `.` separators.
+- Updated dependencies
+  - @backstage/config@1.1.1
+  - @backstage/types@1.1.1
+  - @backstage/version-bridge@1.0.7
+
+## 1.8.1-next.0
+
+### Patch Changes
+
+- 03d0b6dcdc: Removed the alpha `convertLegacyRouteRef` utility, which as been moved to `@backstage/core-compat-api`
+- Updated dependencies
+  - @backstage/config@1.1.1
+  - @backstage/types@1.1.1
+  - @backstage/version-bridge@1.0.7
+
 ## 1.8.0
 
 ### Minor Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/core-plugin-api",
-  "version": "1.8.0",
+  "version": "1.8.1-next.1",
   "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, AnyRouteRefParams as AnyRouteRefParams$1, RouteRef as RouteRef$1, SubRouteRef as SubRouteRef$1, ExternalRouteRef as ExternalRouteRef$1 } from '@backstage/core-plugin-api';
+import { ApiRef } from '@backstage/core-plugin-api';
 import { Observable } from '@backstage/types';
 
 /**
@@ -89,30 +89,44 @@ interface TranslationRef<TId extends string = string, TMessages extends {
     id: TId;
     T: TMessages;
 }
+/** @ignore */
+type AnyNestedMessages = {
+    [key in string]: AnyNestedMessages | string;
+};
+/**
+ * Flattens a nested message declaration into a flat object with dot-separated keys.
+ *
+ * @ignore
+ */
+type FlattenedMessages<TMessages extends AnyNestedMessages> = {
+    [TKey in keyof TMessages]: (_: TMessages[TKey] extends infer TValue ? TValue extends AnyNestedMessages ? FlattenedMessages<TValue> extends infer TNested ? {
+        [TNestedKey in keyof TNested as `${TKey & string}.${TNestedKey & string}`]: TNested[TNestedKey];
+    } : never : {
+        [_ in TKey]: TValue;
+    } : never) => void;
+}[keyof TMessages] extends (_: infer TIntersection) => void ? {
+    readonly [TExpandKey in keyof TIntersection]: TIntersection[TExpandKey];
+} : never;
 /** @alpha */
-interface TranslationRefOptions<TId extends string, TMessages extends {
-    [key in string]: string;
-}, TTranslations extends {
+interface TranslationRefOptions<TId extends string, TNestedMessages extends AnyNestedMessages, TTranslations extends {
     [language in string]: () => Promise<{
         default: {
-            [key in keyof TMessages]: string | null;
+            [key in keyof FlattenedMessages<TNestedMessages>]: string | null;
         };
     }>;
 }> {
     id: TId;
-    messages: TMessages;
+    messages: TNestedMessages;
     translations?: TTranslations;
 }
 /** @alpha */
-declare function createTranslationRef<TId extends string, const TMessages extends {
-    [key in string]: string;
-}, TTranslations extends {
+declare function createTranslationRef<TId extends string, const TNestedMessages extends AnyNestedMessages, TTranslations extends {
     [language in string]: () => Promise<{
         default: {
-            [key in keyof TMessages]: string | null;
+            [key in keyof FlattenedMessages<TNestedMessages>]: string | null;
         };
     }>;
-}>(config: TranslationRefOptions<TId, TMessages, TTranslations>): TranslationRef<TId, TMessages>;
+}>(config: TranslationRefOptions<TId, TNestedMessages, TTranslations>): TranslationRef<TId, FlattenedMessages<TNestedMessages>>;
 
 /**
  * Base translation options.
@@ -391,91 +405,4 @@ declare const useTranslationRef: <TMessages extends {
     t: TranslationFunction<TMessages>;
 };
 
-/**
- * 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 };
+export { AppLanguageApi, TranslationApi, TranslationFunction, TranslationMessages, TranslationMessagesOptions, TranslationRef, TranslationRefOptions, TranslationResource, TranslationResourceOptions, TranslationSnapshot, appLanguageApiRef, createTranslationMessages, createTranslationRef, createTranslationResource, translationApiRef, useTranslationRef };

package/dist/alpha.esm.js

@@ -1,7 +1,6 @@
 import { useState, useMemo, useCallback, useEffect, useRef } from 'react';
-import { u as useApi, s as errorApiRef, r as routeRefType } from './esm/types-08c0ee05.esm.js';
+import { u as useApi, r as errorApiRef } from './esm/StorageApi-2de4f480.esm.js';
 import { createApiRef } from '@backstage/core-plugin-api';
-import 'react-router-dom';
 import '@backstage/version-bridge';
 
 function createTranslationMessages(options) {
@@ -32,61 +31,77 @@ function createTranslationResource(options) {
   };
 }
 
-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);
+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;
 };
-var __accessCheck$2 = (obj, member, msg) => {
+var __accessCheck = (obj, member, msg) => {
   if (!member.has(obj))
     throw TypeError("Cannot " + msg);
 };
-var __privateGet$2 = (obj, member, getter) => {
-  __accessCheck$2(obj, member, "read from private field");
+var __privateGet = (obj, member, getter) => {
+  __accessCheck(obj, member, "read from private field");
   return getter ? getter.call(obj) : member.get(obj);
 };
-var __privateAdd$2 = (obj, member, value) => {
+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$2 = (obj, member, value, setter) => {
-  __accessCheck$2(obj, member, "write to private field");
+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 _id$1, _messages, _resources;
+var _id, _messages, _resources;
+function flattenMessages(nested) {
+  const entries = new Array();
+  function visit(obj, prefix) {
+    for (const [key, value] of Object.entries(obj)) {
+      if (typeof value === "string") {
+        entries.push([prefix + key, value]);
+      } else {
+        visit(value, `${prefix}${key}.`);
+      }
+    }
+  }
+  visit(nested, "");
+  return Object.fromEntries(entries);
+}
 class TranslationRefImpl {
   constructor(options) {
-    __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);
+    __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, flattenMessages(
+      options.messages
+    ));
   }
   get id() {
-    return __privateGet$2(this, _id$1);
+    return __privateGet(this, _id);
   }
   get T() {
     throw new Error("Not implemented");
   }
   getDefaultMessages() {
-    return __privateGet$2(this, _messages);
+    return __privateGet(this, _messages);
   }
   setDefaultResource(resources) {
-    __privateSet$2(this, _resources, resources);
+    __privateSet(this, _resources, resources);
   }
   getDefaultResource() {
-    return __privateGet$2(this, _resources);
+    return __privateGet(this, _resources);
   }
   toString() {
     return `TranslationRef{id=${this.id}}`;
   }
 }
-_id$1 = new WeakMap();
+_id = new WeakMap();
 _messages = new WeakMap();
 _resources = new WeakMap();
 function createTranslationRef(config) {
@@ -175,313 +190,5 @@ const useTranslationRef = (translationRef) => {
   return { t: snapshot.t };
 };
 
-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 };
+export { appLanguageApiRef, createTranslationMessages, createTranslationRef, createTranslationResource, translationApiRef, useTranslationRef };
 //# sourceMappingURL=alpha.esm.js.map