@backstage/plugin-catalog-react 1.11.4-next.1 → 1.12.0-next.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @backstage/plugin-catalog-react
 
+## 1.12.0-next.2
+
+### Minor Changes
+
+- 8834daf: Updated the presentation API to return a promise, in addition to the snapshot and observable that were there before. This makes it much easier to consume the API in a non-React context.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/core-components@0.14.7-next.2
+  - @backstage/frontend-plugin-api@0.6.5-next.1
+  - @backstage/integration-react@1.1.27-next.0
+
 ## 1.11.4-next.1
 
 ### Patch Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-catalog-react",
-  "version": "1.11.4-next.1",
+  "version": "1.12.0-next.2",
   "main": "../dist/alpha.esm.js",
   "module": "../dist/alpha.esm.js",
   "types": "../dist/alpha.d.ts"

package/dist/apis/EntityPresentationApi/EntityPresentationApi.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"EntityPresentationApi.esm.js","sources":["../../../src/apis/EntityPresentationApi/EntityPresentationApi.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity } from '@backstage/catalog-model';\nimport {\n  ApiRef,\n  IconComponent,\n  createApiRef,\n} from '@backstage/core-plugin-api';\nimport { Observable } from '@backstage/types';\n\n/**\n * An API that handles how to represent entities in the interface.\n *\n * @public\n */\nexport const entityPresentationApiRef: ApiRef<EntityPresentationApi> =\n  createApiRef({\n    id: 'plugin.catalog.entity-presentation',\n  });\n\n/**\n * The visual presentation of an entity reference at some point in time.\n *\n * @public\n */\nexport interface EntityRefPresentationSnapshot {\n  /**\n   * The ref to the entity that this snapshot represents.\n   *\n   * @remarks\n   *\n   * Note that when the input data was broken or had missing vital pieces of\n   * information, this string may contain placeholders such as \"unknown\". You\n   * can therefore not necessarily assume that the ref is completely valid and\n   * usable for example for forming a clickable link to the entity.\n   */\n  entityRef: string;\n  /**\n   * A string that can be used as a plain representation of the entity, for\n   * example in a header or a link.\n   *\n   * @remarks\n   *\n   * The title may be short and not contain all of the information that the\n   * entity holds. When rendering the primary title, you may also want to\n   * make sure to add more contextual information nearby such as the icon or\n   * secondary title, since the primary could for example just be the\n   * `metadata.name` of the entity which might be ambiguous to the reader.\n   */\n  primaryTitle: string;\n  /**\n   * Optionally, some additional textual information about the entity, to be\n   * used as a clarification on top of the primary title.\n   *\n   * @remarks\n   *\n   * This text can for example be rendered in a tooltip or be used as a\n   * subtitle. It may not be sufficient to display on its own; it should\n   * typically be used in conjunction with the primary title. It can contain\n   * such information as the entity ref and/or a `spec.type` etc.\n   */\n  secondaryTitle?: string;\n  /**\n   * Optionally, an icon that represents the kind/type of entity.\n   *\n   * @remarks\n   *\n   * This icon should ideally be easily recognizable as the kind of entity, and\n   * be used consistently throughout the Backstage interface. It can be rendered\n   * both in larger formats such as in a header, or in smaller formats such as\n   * inline with regular text, so bear in mind that the legibility should be\n   * high in both cases.\n   *\n   * A value of `false` here indicates the desire to not have an icon present\n   * for the given implementation. A value of `undefined` leaves it at the\n   * discretion of the display layer to choose what to do (such as for example\n   * showing a fallback icon).\n   */\n  Icon?: IconComponent | undefined | false;\n}\n\n/**\n * The visual presentation of an entity reference.\n *\n * @public\n */\nexport interface EntityRefPresentation {\n  /**\n   * The representation that's suitable to use for this entity right now.\n   */\n  snapshot: EntityRefPresentationSnapshot;\n  /**\n   * Some presentation implementations support emitting updated snapshots over\n   * time, for example after retrieving additional data from the catalog or\n   * elsewhere.\n   */\n  update$?: Observable<EntityRefPresentationSnapshot>;\n}\n\n/**\n * An API that decides how to visually represent entities in the interface.\n *\n * @remarks\n *\n * Most consumers will want to use the {@link useEntityPresentation} hook\n * instead of this interface directly.\n *\n * @public\n */\nexport interface EntityPresentationApi {\n  /**\n   * Fetches the presentation for an entity.\n   *\n   * @param entityOrRef - Either an entity, or a string ref to it. If you pass\n   *   in an entity, it is assumed that it is not a partial one - i.e. only pass\n   *   in an entity if you know that it was fetched in such a way that it\n   *   contains all of the fields that the representation renderer needs.\n   * @param context - Contextual information that may affect the presentation.\n   */\n  forEntity(\n    entityOrRef: Entity | string,\n    context?: {\n      defaultKind?: string;\n      defaultNamespace?: string;\n    },\n  ): EntityRefPresentation;\n}\n"],"names":[],"mappings":";;AA6BO,MAAM,2BACX,YAAa,CAAA;AAAA,EACX,EAAI,EAAA,oCAAA;AACN,CAAC;;;;"}
+{"version":3,"file":"EntityPresentationApi.esm.js","sources":["../../../src/apis/EntityPresentationApi/EntityPresentationApi.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity } from '@backstage/catalog-model';\nimport {\n  ApiRef,\n  IconComponent,\n  createApiRef,\n} from '@backstage/core-plugin-api';\nimport { Observable } from '@backstage/types';\n\n/**\n * An API that handles how to represent entities in the interface.\n *\n * @public\n */\nexport const entityPresentationApiRef: ApiRef<EntityPresentationApi> =\n  createApiRef({\n    id: 'plugin.catalog.entity-presentation',\n  });\n\n/**\n * The visual presentation of an entity reference at some point in time.\n *\n * @public\n */\nexport interface EntityRefPresentationSnapshot {\n  /**\n   * The ref to the entity that this snapshot represents.\n   *\n   * @remarks\n   *\n   * Note that when the input data was broken or had missing vital pieces of\n   * information, this string may contain placeholders such as \"unknown\". You\n   * can therefore not necessarily assume that the ref is completely valid and\n   * usable for example for forming a clickable link to the entity.\n   */\n  entityRef: string;\n  /**\n   * A string that can be used as a plain representation of the entity, for\n   * example in a header or a link.\n   *\n   * @remarks\n   *\n   * The title may be short and not contain all of the information that the\n   * entity holds. When rendering the primary title, you may also want to\n   * make sure to add more contextual information nearby such as the icon or\n   * secondary title, since the primary could for example just be the\n   * `metadata.name` of the entity which might be ambiguous to the reader.\n   */\n  primaryTitle: string;\n  /**\n   * Optionally, some additional textual information about the entity, to be\n   * used as a clarification on top of the primary title.\n   *\n   * @remarks\n   *\n   * This text can for example be rendered in a tooltip or be used as a\n   * subtitle. It may not be sufficient to display on its own; it should\n   * typically be used in conjunction with the primary title. It can contain\n   * such information as the entity ref and/or a `spec.type` etc.\n   */\n  secondaryTitle?: string;\n  /**\n   * Optionally, an icon that represents the kind/type of entity.\n   *\n   * @remarks\n   *\n   * This icon should ideally be easily recognizable as the kind of entity, and\n   * be used consistently throughout the Backstage interface. It can be rendered\n   * both in larger formats such as in a header, or in smaller formats such as\n   * inline with regular text, so bear in mind that the legibility should be\n   * high in both cases.\n   *\n   * A value of `false` here indicates the desire to not have an icon present\n   * for the given implementation. A value of `undefined` leaves it at the\n   * discretion of the display layer to choose what to do (such as for example\n   * showing a fallback icon).\n   */\n  Icon?: IconComponent | undefined | false;\n}\n\n/**\n * The visual presentation of an entity reference.\n *\n * @public\n */\nexport interface EntityRefPresentation {\n  /**\n   * The representation that's suitable to use for this entity right now.\n   */\n  snapshot: EntityRefPresentationSnapshot;\n  /**\n   * Some presentation implementations support emitting updated snapshots over\n   * time, for example after retrieving additional data from the catalog or\n   * elsewhere.\n   */\n  update$?: Observable<EntityRefPresentationSnapshot>;\n  /**\n   * A promise that resolves to a usable entity presentation.\n   */\n  promise: Promise<EntityRefPresentationSnapshot>;\n}\n\n/**\n * An API that decides how to visually represent entities in the interface.\n *\n * @remarks\n *\n * Most consumers will want to use the {@link useEntityPresentation} hook\n * instead of this interface directly.\n *\n * @public\n */\nexport interface EntityPresentationApi {\n  /**\n   * Fetches the presentation for an entity.\n   *\n   * @param entityOrRef - Either an entity, or a string ref to it. If you pass\n   *   in an entity, it is assumed that it is not a partial one - i.e. only pass\n   *   in an entity if you know that it was fetched in such a way that it\n   *   contains all of the fields that the representation renderer needs.\n   * @param context - Contextual information that may affect the presentation.\n   */\n  forEntity(\n    entityOrRef: Entity | string,\n    context?: {\n      defaultKind?: string;\n      defaultNamespace?: string;\n    },\n  ): EntityRefPresentation;\n}\n"],"names":[],"mappings":";;AA6BO,MAAM,2BACX,YAAa,CAAA;AAAA,EACX,EAAI,EAAA,oCAAA;AACN,CAAC;;;;"}

package/dist/apis/EntityPresentationApi/useEntityPresentation.esm.js

@@ -16,7 +16,8 @@ function useEntityPresentation(entityOrRef, context) {
   const presentation = useMemo(
     () => {
       if (!entityPresentationApi) {
-        return { snapshot: defaultEntityPresentation(entityOrRef, context) };
+        const fallback = defaultEntityPresentation(entityOrRef, context);
+        return { snapshot: fallback, promise: Promise.resolve(fallback) };
       }
       return entityPresentationApi.forEntity(
         typeof entityOrRef === "string" || "metadata" in entityOrRef ? entityOrRef : stringifyEntityRef(entityOrRef),

package/dist/apis/EntityPresentationApi/useEntityPresentation.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"useEntityPresentation.esm.js","sources":["../../../src/apis/EntityPresentationApi/useEntityPresentation.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  CompoundEntityRef,\n  Entity,\n  stringifyEntityRef,\n} from '@backstage/catalog-model';\nimport { useApiHolder } from '@backstage/core-plugin-api';\nimport { useMemo } from 'react';\nimport {\n  EntityRefPresentation,\n  EntityRefPresentationSnapshot,\n  entityPresentationApiRef,\n} from './EntityPresentationApi';\nimport { defaultEntityPresentation } from './defaultEntityPresentation';\nimport { useUpdatingObservable } from './useUpdatingObservable';\n\n/**\n * Returns information about how to represent an entity in the interface.\n *\n * @public\n * @param entityOrRef - The entity to represent, or an entity ref to it. If you\n *   pass in an entity, it is assumed that it is NOT a partial one - i.e. only\n *   pass in an entity if you know that it was fetched in such a way that it\n *   contains all of the fields that the representation renderer needs.\n * @param context - Optional context that control details of the presentation.\n * @returns A snapshot of the entity presentation, which may change over time\n */\nexport function useEntityPresentation(\n  entityOrRef: Entity | CompoundEntityRef | string,\n  context?: {\n    defaultKind?: string;\n    defaultNamespace?: string;\n  },\n): EntityRefPresentationSnapshot {\n  // Defensively allow for a missing presentation API, which makes this hook\n  // safe to use in tests.\n  const apis = useApiHolder();\n  const entityPresentationApi = apis.get(entityPresentationApiRef);\n\n  const deps = [\n    entityPresentationApi,\n    JSON.stringify(entityOrRef),\n    JSON.stringify(context || null),\n  ];\n\n  const presentation = useMemo<EntityRefPresentation>(\n    () => {\n      if (!entityPresentationApi) {\n        return { snapshot: defaultEntityPresentation(entityOrRef, context) };\n      }\n\n      return entityPresentationApi.forEntity(\n        typeof entityOrRef === 'string' || 'metadata' in entityOrRef\n          ? entityOrRef\n          : stringifyEntityRef(entityOrRef),\n        context,\n      );\n    },\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    deps,\n  );\n\n  // NOTE(freben): We intentionally do not use the plain useObservable from the\n  // react-use library here. That hook does not support a dependencies array,\n  // and also it only subscribes once to the initially passed in observable and\n  // won't properly react when either initial value or the actual observable\n  // changes.\n  return useUpdatingObservable(presentation.snapshot, presentation.update$, [\n    presentation,\n  ]);\n}\n"],"names":[],"mappings":";;;;;;;AA0CgB,SAAA,qBAAA,CACd,aACA,OAI+B,EAAA;AAG/B,EAAA,MAAM,OAAO,YAAa,EAAA,CAAA;AAC1B,EAAM,MAAA,qBAAA,GAAwB,IAAK,CAAA,GAAA,CAAI,wBAAwB,CAAA,CAAA;AAE/D,EAAA,MAAM,IAAO,GAAA;AAAA,IACX,qBAAA;AAAA,IACA,IAAA,CAAK,UAAU,WAAW,CAAA;AAAA,IAC1B,IAAA,CAAK,SAAU,CAAA,OAAA,IAAW,IAAI,CAAA;AAAA,GAChC,CAAA;AAEA,EAAA,MAAM,YAAe,GAAA,OAAA;AAAA,IACnB,MAAM;AACJ,MAAA,IAAI,CAAC,qBAAuB,EAAA;AAC1B,QAAA,OAAO,EAAE,QAAA,EAAU,yBAA0B,CAAA,WAAA,EAAa,OAAO,CAAE,EAAA,CAAA;AAAA,OACrE;AAEA,MAAA,OAAO,qBAAsB,CAAA,SAAA;AAAA,QAC3B,OAAO,WAAgB,KAAA,QAAA,IAAY,cAAc,WAC7C,GAAA,WAAA,GACA,mBAAmB,WAAW,CAAA;AAAA,QAClC,OAAA;AAAA,OACF,CAAA;AAAA,KACF;AAAA;AAAA,IAEA,IAAA;AAAA,GACF,CAAA;AAOA,EAAA,OAAO,qBAAsB,CAAA,YAAA,CAAa,QAAU,EAAA,YAAA,CAAa,OAAS,EAAA;AAAA,IACxE,YAAA;AAAA,GACD,CAAA,CAAA;AACH;;;;"}
+{"version":3,"file":"useEntityPresentation.esm.js","sources":["../../../src/apis/EntityPresentationApi/useEntityPresentation.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  CompoundEntityRef,\n  Entity,\n  stringifyEntityRef,\n} from '@backstage/catalog-model';\nimport { useApiHolder } from '@backstage/core-plugin-api';\nimport { useMemo } from 'react';\nimport {\n  EntityRefPresentation,\n  EntityRefPresentationSnapshot,\n  entityPresentationApiRef,\n} from './EntityPresentationApi';\nimport { defaultEntityPresentation } from './defaultEntityPresentation';\nimport { useUpdatingObservable } from './useUpdatingObservable';\n\n/**\n * Returns information about how to represent an entity in the interface.\n *\n * @public\n * @param entityOrRef - The entity to represent, or an entity ref to it. If you\n *   pass in an entity, it is assumed that it is NOT a partial one - i.e. only\n *   pass in an entity if you know that it was fetched in such a way that it\n *   contains all of the fields that the representation renderer needs.\n * @param context - Optional context that control details of the presentation.\n * @returns A snapshot of the entity presentation, which may change over time\n */\nexport function useEntityPresentation(\n  entityOrRef: Entity | CompoundEntityRef | string,\n  context?: {\n    defaultKind?: string;\n    defaultNamespace?: string;\n  },\n): EntityRefPresentationSnapshot {\n  // Defensively allow for a missing presentation API, which makes this hook\n  // safe to use in tests.\n  const apis = useApiHolder();\n  const entityPresentationApi = apis.get(entityPresentationApiRef);\n\n  const deps = [\n    entityPresentationApi,\n    JSON.stringify(entityOrRef),\n    JSON.stringify(context || null),\n  ];\n\n  const presentation = useMemo<EntityRefPresentation>(\n    () => {\n      if (!entityPresentationApi) {\n        const fallback = defaultEntityPresentation(entityOrRef, context);\n        return { snapshot: fallback, promise: Promise.resolve(fallback) };\n      }\n\n      return entityPresentationApi.forEntity(\n        typeof entityOrRef === 'string' || 'metadata' in entityOrRef\n          ? entityOrRef\n          : stringifyEntityRef(entityOrRef),\n        context,\n      );\n    },\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    deps,\n  );\n\n  // NOTE(freben): We intentionally do not use the plain useObservable from the\n  // react-use library here. That hook does not support a dependencies array,\n  // and also it only subscribes once to the initially passed in observable and\n  // won't properly react when either initial value or the actual observable\n  // changes.\n  return useUpdatingObservable(presentation.snapshot, presentation.update$, [\n    presentation,\n  ]);\n}\n"],"names":[],"mappings":";;;;;;;AA0CgB,SAAA,qBAAA,CACd,aACA,OAI+B,EAAA;AAG/B,EAAA,MAAM,OAAO,YAAa,EAAA,CAAA;AAC1B,EAAM,MAAA,qBAAA,GAAwB,IAAK,CAAA,GAAA,CAAI,wBAAwB,CAAA,CAAA;AAE/D,EAAA,MAAM,IAAO,GAAA;AAAA,IACX,qBAAA;AAAA,IACA,IAAA,CAAK,UAAU,WAAW,CAAA;AAAA,IAC1B,IAAA,CAAK,SAAU,CAAA,OAAA,IAAW,IAAI,CAAA;AAAA,GAChC,CAAA;AAEA,EAAA,MAAM,YAAe,GAAA,OAAA;AAAA,IACnB,MAAM;AACJ,MAAA,IAAI,CAAC,qBAAuB,EAAA;AAC1B,QAAM,MAAA,QAAA,GAAW,yBAA0B,CAAA,WAAA,EAAa,OAAO,CAAA,CAAA;AAC/D,QAAA,OAAO,EAAE,QAAU,EAAA,QAAA,EAAU,SAAS,OAAQ,CAAA,OAAA,CAAQ,QAAQ,CAAE,EAAA,CAAA;AAAA,OAClE;AAEA,MAAA,OAAO,qBAAsB,CAAA,SAAA;AAAA,QAC3B,OAAO,WAAgB,KAAA,QAAA,IAAY,cAAc,WAC7C,GAAA,WAAA,GACA,mBAAmB,WAAW,CAAA;AAAA,QAClC,OAAA;AAAA,OACF,CAAA;AAAA,KACF;AAAA;AAAA,IAEA,IAAA;AAAA,GACF,CAAA;AAOA,EAAA,OAAO,qBAAsB,CAAA,YAAA,CAAa,QAAU,EAAA,YAAA,CAAa,OAAS,EAAA;AAAA,IACxE,YAAA;AAAA,GACD,CAAA,CAAA;AACH;;;;"}

package/dist/index.d.ts

@@ -102,6 +102,10 @@ interface EntityRefPresentation {
      * elsewhere.
      */
     update$?: Observable<EntityRefPresentationSnapshot>;
+    /**
+     * A promise that resolves to a usable entity presentation.
+     */
+    promise: Promise<EntityRefPresentationSnapshot>;
 }
 /**
  * An API that decides how to visually represent entities in the interface.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-catalog-react",
   "description": "A frontend library that helps other Backstage plugins interact with the catalog",
-  "version": "1.11.4-next.1",
+  "version": "1.12.0-next.2",
   "main": "./dist/index.esm.js",
   "types": "./dist/index.d.ts",
   "license": "Apache-2.0",
@@ -46,11 +46,11 @@
   "dependencies": {
     "@backstage/catalog-client": "^1.6.5-next.0",
     "@backstage/catalog-model": "^1.5.0-next.0",
-    "@backstage/core-components": "^0.14.6-next.1",
+    "@backstage/core-components": "^0.14.7-next.2",
     "@backstage/core-plugin-api": "^1.9.2",
     "@backstage/errors": "^1.2.4",
     "@backstage/frontend-plugin-api": "^0.6.5-next.1",
-    "@backstage/integration-react": "^1.1.26",
+    "@backstage/integration-react": "^1.1.27-next.0",
     "@backstage/plugin-catalog-common": "^1.0.23-next.0",
     "@backstage/plugin-permission-common": "^0.7.13",
     "@backstage/plugin-permission-react": "^0.4.22",
@@ -75,7 +75,7 @@
     "react-router-dom": "6.0.0-beta.0 || ^6.3.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.26.5-next.0",
+    "@backstage/cli": "^0.26.5-next.1",
     "@backstage/core-app-api": "^1.12.4",
     "@backstage/plugin-catalog-common": "^1.0.23-next.0",
     "@backstage/plugin-scaffolder-common": "^1.5.2-next.1",