@backstage/plugin-catalog-react 0.0.0-nightly-20220217022146 → 0.0.0-nightly-20220218022735

package/CHANGELOG.md

@@ -1,6 +1,14 @@
 # @backstage/plugin-catalog-react
 
-## 0.0.0-nightly-20220217022146
+## 0.0.0-nightly-20220218022735
+
+### Minor Changes
+
+- e2e0b6625c: Improved API documentation.
+
+  **BREAKING**: The individual table column factories (e.g. `createEntityRefColumn`) are now no longer available directly, but only through `EntityTable.columns`.
+
+## 0.6.15
 
 ### Patch Changes
 
@@ -17,16 +25,16 @@
 - 27eccab216: Replaces use of deprecated catalog-model constants.
 - 7aeb491394: Replace use of deprecated `ENTITY_DEFAULT_NAMESPACE` constant with `DEFAULT_NAMESPACE`.
 - Updated dependencies
-  - @backstage/catalog-client@0.0.0-nightly-20220217022146
-  - @backstage/core-components@0.0.0-nightly-20220217022146
-  - @backstage/core-plugin-api@0.0.0-nightly-20220217022146
-  - @backstage/errors@0.0.0-nightly-20220217022146
-  - @backstage/integration@0.0.0-nightly-20220217022146
-  - @backstage/plugin-permission-common@0.0.0-nightly-20220217022146
-  - @backstage/plugin-permission-react@0.0.0-nightly-20220217022146
-  - @backstage/catalog-model@0.0.0-nightly-20220217022146
-  - @backstage/types@0.0.0-nightly-20220217022146
-  - @backstage/version-bridge@0.0.0-nightly-20220217022146
+  - @backstage/catalog-client@0.7.0
+  - @backstage/core-components@0.8.9
+  - @backstage/core-plugin-api@0.6.1
+  - @backstage/errors@0.2.1
+  - @backstage/integration@0.7.3
+  - @backstage/plugin-permission-common@0.5.0
+  - @backstage/plugin-permission-react@0.3.1
+  - @backstage/catalog-model@0.10.0
+  - @backstage/types@0.1.2
+  - @backstage/version-bridge@0.1.2
 
 ## 0.6.14
 

package/dist/index.d.ts

@@ -15,6 +15,10 @@ import { ScmIntegrationRegistry } from '@backstage/integration';
 import { Overrides } from '@material-ui/core/styles/overrides';
 import { StyleRules } from '@material-ui/core/styles/withStyles';
 
+/**
+ * The API reference for the {@link @backstage/catalog-client#CatalogApi}.
+ * @public
+ */
 declare const catalogApiRef: _backstage_core_plugin_api.ApiRef<CatalogApi>;
 
 /**
@@ -116,62 +120,19 @@ declare type EntityRefLinksProps = {
  */
 declare const EntityRefLinks: ({ entityRefs, defaultKind, ...linkProps }: EntityRefLinksProps) => JSX.Element;
 
+/** @public */
 declare function formatEntityRefTitle(entityRef: Entity | EntityName, opts?: {
     defaultKind?: string;
 }): string;
 
 /** @public */
 declare type CatalogReactEntitySearchBarClassKey = 'searchToolbar' | 'input';
-/** @public */
+/**
+ * Renders search bar for filtering the entity list.
+ * @public
+ */
 declare const EntitySearchBar: () => JSX.Element;
 
-/** @public */
-declare function createEntityRefColumn<T extends Entity>(options: {
-    defaultKind?: string;
-}): TableColumn<T>;
-/** @public */
-declare function createEntityRelationColumn<T extends Entity>({ title, relation, defaultKind, filter: entityFilter, }: {
-    title: string;
-    relation: string;
-    defaultKind?: string;
-    filter?: {
-        kind: string;
-    };
-}): TableColumn<T>;
-/** @public */
-declare function createOwnerColumn<T extends Entity>(): TableColumn<T>;
-/** @public */
-declare function createDomainColumn<T extends Entity>(): TableColumn<T>;
-/** @public */
-declare function createSystemColumn<T extends Entity>(): TableColumn<T>;
-/** @public */
-declare function createMetadataDescriptionColumn<T extends Entity>(): TableColumn<T>;
-/** @public */
-declare function createSpecLifecycleColumn<T extends Entity>(): TableColumn<T>;
-/** @public */
-declare function createSpecTypeColumn<T extends Entity>(): TableColumn<T>;
-
-declare const columnFactories_createEntityRefColumn: typeof createEntityRefColumn;
-declare const columnFactories_createEntityRelationColumn: typeof createEntityRelationColumn;
-declare const columnFactories_createOwnerColumn: typeof createOwnerColumn;
-declare const columnFactories_createDomainColumn: typeof createDomainColumn;
-declare const columnFactories_createSystemColumn: typeof createSystemColumn;
-declare const columnFactories_createMetadataDescriptionColumn: typeof createMetadataDescriptionColumn;
-declare const columnFactories_createSpecLifecycleColumn: typeof createSpecLifecycleColumn;
-declare const columnFactories_createSpecTypeColumn: typeof createSpecTypeColumn;
-declare namespace columnFactories {
-  export {
-    columnFactories_createEntityRefColumn as createEntityRefColumn,
-    columnFactories_createEntityRelationColumn as createEntityRelationColumn,
-    columnFactories_createOwnerColumn as createOwnerColumn,
-    columnFactories_createDomainColumn as createDomainColumn,
-    columnFactories_createSystemColumn as createSystemColumn,
-    columnFactories_createMetadataDescriptionColumn as createMetadataDescriptionColumn,
-    columnFactories_createSpecLifecycleColumn as createSpecLifecycleColumn,
-    columnFactories_createSpecTypeColumn as createSpecTypeColumn,
-  };
-}
-
 /**
  * Props for {@link EntityTable}.
  *
@@ -190,12 +151,51 @@ interface EntityTableProps<T extends Entity> {
  *
  * @public
  */
-declare function EntityTable<T extends Entity>(props: EntityTableProps<T>): JSX.Element;
-declare namespace EntityTable {
-    var columns: typeof columnFactories;
-    var systemEntityColumns: TableColumn<_backstage_catalog_model.SystemEntity>[];
-    var componentEntityColumns: TableColumn<_backstage_catalog_model.ComponentEntity>[];
-}
+declare const EntityTable: {
+    <T extends Entity>(props: EntityTableProps<T>): JSX.Element;
+    columns: Readonly<{
+        createEntityRefColumn<T_1 extends Entity>(options: {
+            defaultKind?: string | undefined;
+        }): TableColumn<T_1>;
+        createEntityRelationColumn<T_2 extends Entity>({ title, relation, defaultKind, filter: entityFilter, }: {
+            title: string;
+            relation: string;
+            defaultKind?: string | undefined;
+            filter?: {
+                kind: string;
+            } | undefined;
+        }): TableColumn<T_2>;
+        createOwnerColumn<T_3 extends Entity>(): TableColumn<T_3>;
+        createDomainColumn<T_4 extends Entity>(): TableColumn<T_4>;
+        createSystemColumn<T_5 extends Entity>(): TableColumn<T_5>;
+        createMetadataDescriptionColumn<T_6 extends Entity>(): TableColumn<T_6>;
+        createSpecLifecycleColumn<T_7 extends Entity>(): TableColumn<T_7>;
+        createSpecTypeColumn<T_8 extends Entity>(): TableColumn<T_8>;
+    }>;
+    systemEntityColumns: TableColumn<_backstage_catalog_model.SystemEntity>[];
+    componentEntityColumns: TableColumn<_backstage_catalog_model.ComponentEntity>[];
+};
+
+/** @public */
+declare const columnFactories: Readonly<{
+    createEntityRefColumn<T extends Entity>(options: {
+        defaultKind?: string;
+    }): TableColumn<T>;
+    createEntityRelationColumn<T_1 extends Entity>({ title, relation, defaultKind, filter: entityFilter, }: {
+        title: string;
+        relation: string;
+        defaultKind?: string | undefined;
+        filter?: {
+            kind: string;
+        } | undefined;
+    }): TableColumn<T_1>;
+    createOwnerColumn<T_2 extends Entity>(): TableColumn<T_2>;
+    createDomainColumn<T_3 extends Entity>(): TableColumn<T_3>;
+    createSystemColumn<T_4 extends Entity>(): TableColumn<T_4>;
+    createMetadataDescriptionColumn<T_5 extends Entity>(): TableColumn<T_5>;
+    createSpecLifecycleColumn<T_6 extends Entity>(): TableColumn<T_6>;
+    createSpecTypeColumn<T_7 extends Entity>(): TableColumn<T_7>;
+}>;
 
 /** @public */
 declare type CatalogReactEntityTagPickerClassKey = 'input';
@@ -214,16 +214,20 @@ interface EntityTypePickerProps {
 /** @public */
 declare const EntityTypePicker: (props: EntityTypePickerProps) => JSX.Element | null;
 
-declare type Props$1 = ComponentProps<typeof IconButton> & {
+/** @public */
+declare type FavoriteEntityProps = ComponentProps<typeof IconButton> & {
     entity: Entity;
 };
+/** @public */
 declare const favoriteEntityTooltip: (isStarred: boolean) => "Remove from favorites" | "Add to favorites";
+/** @public */
 declare const favoriteEntityIcon: (isStarred: boolean) => JSX.Element;
 /**
  * IconButton for showing if a current entity is starred and adding/removing it from the favorite entities
  * @param props - MaterialUI IconButton props extended by required `entity` prop
+ * @public
  */
-declare const FavoriteEntity: (props: Props$1) => JSX.Element;
+declare const FavoriteEntity: (props: FavoriteEntityProps) => JSX.Element;
 
 /**
  * A dialog that lets users inspect the low level details of their entities.
@@ -236,14 +240,17 @@ declare function InspectEntityDialog(props: {
     onClose: () => void;
 }): JSX.Element | null;
 
-declare type Props = {
+/** @public */
+declare type UnregisterEntityDialogProps = {
     open: boolean;
     onConfirm: () => any;
     onClose: () => any;
     entity: Entity;
 };
-declare const UnregisterEntityDialog: ({ open, onConfirm, onClose, entity, }: Props) => JSX.Element;
+/** @public */
+declare const UnregisterEntityDialog: (props: UnregisterEntityDialogProps) => JSX.Element;
 
+/** @public */
 declare type EntityFilter = {
     /**
      * Get filters to add to the catalog-backend request. These are a dot-delimited field with
@@ -265,16 +272,20 @@ declare type EntityFilter = {
      */
     toQueryValue?: () => string | string[];
 };
+/** @public */
 declare type UserListFilterKind = 'owned' | 'starred' | 'all';
 
 /** @public */
 declare type CatalogReactUserListPickerClassKey = 'root' | 'title' | 'listIcon' | 'menuItem' | 'groupWrapper';
+/** @public */
 declare type UserListPickerProps = {
     initialFilter?: UserListFilterKind;
     availableFilters?: UserListFilterKind[];
 };
-declare const UserListPicker: ({ initialFilter, availableFilters, }: UserListPickerProps) => JSX.Element;
+/** @public */
+declare const UserListPicker: (props: UserListPickerProps) => JSX.Element;
 
+/** @public */
 declare type EntityLoadingStatus = {
     entity?: Entity;
     loading: boolean;
@@ -319,6 +330,7 @@ interface EntityProviderProps {
  * @public
  */
 declare const EntityProvider: ({ entity, children }: EntityProviderProps) => JSX.Element;
+/** @public */
 declare const useEntityFromUrl: () => EntityLoadingStatus;
 /**
  * Grab the current entity from the context and its current loading state.
@@ -334,6 +346,7 @@ declare function useEntity<T extends Entity = Entity>(): {
 
 /**
  * Grabs entity kind, namespace, and name from the location
+ * @public
  */
 declare const useEntityCompoundName: () => {
     kind: string;
@@ -341,12 +354,20 @@ declare const useEntityCompoundName: () => {
     name: string;
 };
 
+/**
+ * Filter entities based on Kind.
+ * @public
+ */
 declare class EntityKindFilter implements EntityFilter {
     readonly value: string;
     constructor(value: string);
     getCatalogFilters(): Record<string, string | string[]>;
     toQueryValue(): string;
 }
+/**
+ * Filters entities based on type
+ * @public
+ */
 declare class EntityTypeFilter implements EntityFilter {
     readonly value: string | string[];
     constructor(value: string | string[]);
@@ -354,29 +375,49 @@ declare class EntityTypeFilter implements EntityFilter {
     getCatalogFilters(): Record<string, string | string[]>;
     toQueryValue(): string[];
 }
+/**
+ * Filters entities based on tag.
+ * @public
+ */
 declare class EntityTagFilter implements EntityFilter {
     readonly values: string[];
     constructor(values: string[]);
     filterEntity(entity: Entity): boolean;
     toQueryValue(): string[];
 }
+/**
+ * Filters entities where the text matches spec, title or tags.
+ * @public
+ */
 declare class EntityTextFilter implements EntityFilter {
     readonly value: string;
     constructor(value: string);
     filterEntity(entity: Entity): boolean;
 }
+/**
+ * Filter matching entities that are owned by group.
+ * @public
+ */
 declare class EntityOwnerFilter implements EntityFilter {
     readonly values: string[];
     constructor(values: string[]);
     filterEntity(entity: Entity): boolean;
     toQueryValue(): string[];
 }
+/**
+ * Filters entities on lifecycle.
+ * @public
+ */
 declare class EntityLifecycleFilter implements EntityFilter {
     readonly values: string[];
     constructor(values: string[]);
     filterEntity(entity: Entity): boolean;
     toQueryValue(): string[];
 }
+/**
+ * Filters entities based on whatever the user has starred or owns them.
+ * @public
+ */
 declare class UserListFilter implements EntityFilter {
     readonly value: UserListFilterKind;
     readonly isOwnedEntity: (entity: Entity) => boolean;
@@ -386,6 +427,7 @@ declare class UserListFilter implements EntityFilter {
     toQueryValue(): string;
 }
 
+/** @public */
 declare type DefaultEntityFilters = {
     kind?: EntityKindFilter;
     type?: EntityTypeFilter;
@@ -395,6 +437,7 @@ declare type DefaultEntityFilters = {
     tags?: EntityTagFilter;
     text?: EntityTextFilter;
 };
+/** @public */
 declare type EntityListContextProps<EntityFilters extends DefaultEntityFilters = DefaultEntityFilters> = {
     /**
      * The currently registered filters, adhering to the shape of DefaultEntityFilters or an extension
@@ -421,10 +464,23 @@ declare type EntityListContextProps<EntityFilters extends DefaultEntityFilters =
     loading: boolean;
     error?: Error;
 };
+/**
+ * Creates new context for entity listing and filtering.
+ * @public
+ */
 declare const EntityListContext: React.Context<EntityListContextProps<any> | undefined>;
+/**
+ * Provides entities and filters for a catalog listing.
+ * @public
+ */
 declare const EntityListProvider: <EntityFilters extends DefaultEntityFilters>({ children, }: PropsWithChildren<{}>) => JSX.Element;
+/**
+ * Hook for interacting with the entity list context provided by the {@link EntityListProvider}.
+ * @public
+ */
 declare function useEntityListProvider<EntityFilters extends DefaultEntityFilters = DefaultEntityFilters>(): EntityListContextProps<EntityFilters>;
 
+/** @public */
 declare type EntityTypeReturn = {
     loading: boolean;
     error?: Error;
@@ -435,9 +491,14 @@ declare type EntityTypeReturn = {
 /**
  * A hook built on top of `useEntityListProvider` for enabling selection of valid `spec.type` values
  * based on the selected EntityKindFilter.
+ * @public
  */
 declare function useEntityTypeFilter(): EntityTypeReturn;
 
+/**
+ * Retrieve a list of unique entity kinds present in the catalog
+ * @public
+ */
 declare function useEntityKinds(): {
     error: Error | undefined;
     loading: boolean;
@@ -446,9 +507,11 @@ declare function useEntityKinds(): {
 
 /**
  * Get the catalog User entity (if any) that matches the logged-in user.
+ * @public
  */
 declare function useOwnUser(): AsyncState<UserEntity | undefined>;
 
+/** @public */
 declare function useRelatedEntities(entity: Entity, { type, kind }: {
     type?: string;
     kind?: string;
@@ -458,12 +521,14 @@ declare function useRelatedEntities(entity: Entity, { type, kind }: {
     error: Error | undefined;
 };
 
+/** @public */
 declare function useStarredEntities(): {
     starredEntities: Set<string>;
     toggleStarredEntity: (entityOrRef: Entity | EntityName | string) => void;
     isStarredEntity: (entityOrRef: Entity | EntityName | string) => boolean;
 };
 
+/** @public */
 declare function useStarredEntity(entityOrRef: Entity | EntityName | string): {
     toggleStarredEntity: () => void;
     isStarredEntity: boolean;
@@ -541,10 +606,12 @@ declare function useEntityPermission(permission: Permission): {
 
 /**
  * @deprecated Use an `ExternalRouteRef` instead, which can point to `catalogPlugin.routes.catalogIndex`.
+ * @public
  */
 declare const rootRoute: _backstage_core_plugin_api.RouteRef<undefined>;
 /**
  * @deprecated Use an `ExternalRouteRef` instead, which can point to `catalogPlugin.routes.catalogIndex`.
+ * @public
  */
 declare const catalogRouteRef: _backstage_core_plugin_api.RouteRef<undefined>;
 /**
@@ -555,6 +622,7 @@ declare const catalogRouteRef: _backstage_core_plugin_api.RouteRef<undefined>;
  *
  * If you want to replace the `EntityPage` from `@backstage/catalog-plugin` in your app,
  * you need to use the `entityRouteRef` as the mount point instead of your own.
+ * @public
  */
 declare const entityRouteRef: _backstage_core_plugin_api.RouteRef<{
     name: string;
@@ -563,43 +631,57 @@ declare const entityRouteRef: _backstage_core_plugin_api.RouteRef<{
 }>;
 /**
  * @deprecated use `entityRouteRef` instead.
+ * @public
  */
 declare const entityRoute: _backstage_core_plugin_api.RouteRef<{
     name: string;
     kind: string;
     namespace: string;
 }>;
+/**
+ * Utility function to get suitable route params for entityRoute, given an
+ * @public
+ */
 declare function entityRouteParams(entity: Entity): {
     readonly kind: string;
     readonly namespace: string;
     readonly name: string;
 };
 
+/** @public */
 declare const MockEntityListContextProvider: ({ children, value, }: React.PropsWithChildren<{
     value?: Partial<EntityListContextProps<DefaultEntityFilters>> | undefined;
 }>) => JSX.Element;
 
+/** @public */
 declare function reduceCatalogFilters(filters: EntityFilter[]): Record<string, string | symbol | (string | symbol)[]>;
+/** @public */
 declare function reduceEntityFilters(filters: EntityFilter[]): (entity: Entity) => boolean;
 
+/** @public */
 declare function getEntityMetadataViewUrl(entity: Entity): string | undefined;
+/** @public */
 declare function getEntityMetadataEditUrl(entity: Entity): string | undefined;
 
 /**
  * Get the related entity references.
+ * @public
  */
 declare function getEntityRelations(entity: Entity | undefined, relationType: string, filter?: {
     kind: string;
 }): EntityName[];
 
+/** @public */
 declare type EntitySourceLocation = {
     locationTargetUrl: string;
     integrationType?: string;
 };
+/** @public */
 declare function getEntitySourceLocation(entity: Entity, scmIntegrationsApi: ScmIntegrationRegistry): EntitySourceLocation | undefined;
 
 /**
  * Get the related entity references.
+ * @public
  */
 declare function isOwnerOf(owner: Entity, owned: Entity): boolean;
 
@@ -616,4 +698,4 @@ declare type BackstageOverrides = Overrides & {
     [Name in keyof CatalogReactComponentsNameToClassKey]?: Partial<StyleRules<CatalogReactComponentsNameToClassKey[Name]>>;
 };
 
-export { AsyncEntityProvider, AsyncEntityProviderProps, BackstageOverrides, CatalogReactComponentsNameToClassKey, CatalogReactEntityLifecyclePickerClassKey, CatalogReactEntityOwnerPickerClassKey, CatalogReactEntitySearchBarClassKey, CatalogReactEntityTagPickerClassKey, CatalogReactUserListPickerClassKey, DefaultEntityFilters, DefaultStarredEntitiesApi, EntityContext, EntityFilter, EntityKindFilter, EntityKindPicker, EntityKindPickerProps, EntityLifecycleFilter, EntityLifecyclePicker, EntityListContext, EntityListProvider, EntityOwnerFilter, EntityOwnerPicker, EntityProvider, EntityProviderProps, EntityRefLink, EntityRefLinkProps, EntityRefLinks, EntityRefLinksProps, EntitySearchBar, EntitySourceLocation, EntityTable, EntityTableProps, EntityTagFilter, EntityTagPicker, EntityTextFilter, EntityTypeFilter, EntityTypePicker, EntityTypePickerProps, FavoriteEntity, InspectEntityDialog, MockEntityListContextProvider, StarredEntitiesApi, UnregisterEntityDialog, UserListFilter, UserListFilterKind, UserListPicker, catalogApiRef, catalogRouteRef, entityRoute, entityRouteParams, entityRouteRef, favoriteEntityIcon, favoriteEntityTooltip, formatEntityRefTitle, getEntityMetadataEditUrl, getEntityMetadataViewUrl, getEntityRelations, getEntitySourceLocation, isOwnerOf, loadCatalogOwnerRefs, loadIdentityOwnerRefs, reduceCatalogFilters, reduceEntityFilters, rootRoute, starredEntitiesApiRef, useEntity, useEntityCompoundName, useEntityFromUrl, useEntityKinds, useEntityListProvider, useEntityOwnership, useEntityPermission, useEntityTypeFilter, useOwnUser, useOwnedEntities, useRelatedEntities, useStarredEntities, useStarredEntity };
+export { AsyncEntityProvider, AsyncEntityProviderProps, BackstageOverrides, CatalogReactComponentsNameToClassKey, CatalogReactEntityLifecyclePickerClassKey, CatalogReactEntityOwnerPickerClassKey, CatalogReactEntitySearchBarClassKey, CatalogReactEntityTagPickerClassKey, CatalogReactUserListPickerClassKey, DefaultEntityFilters, DefaultStarredEntitiesApi, EntityContext, EntityFilter, EntityKindFilter, EntityKindPicker, EntityKindPickerProps, EntityLifecycleFilter, EntityLifecyclePicker, EntityListContext, EntityListContextProps, EntityListProvider, EntityLoadingStatus, EntityOwnerFilter, EntityOwnerPicker, EntityProvider, EntityProviderProps, EntityRefLink, EntityRefLinkProps, EntityRefLinks, EntityRefLinksProps, EntitySearchBar, EntitySourceLocation, EntityTable, EntityTableProps, EntityTagFilter, EntityTagPicker, EntityTextFilter, EntityTypeFilter, EntityTypePicker, EntityTypePickerProps, EntityTypeReturn, FavoriteEntity, FavoriteEntityProps, InspectEntityDialog, MockEntityListContextProvider, StarredEntitiesApi, UnregisterEntityDialog, UnregisterEntityDialogProps, UserListFilter, UserListFilterKind, UserListPicker, UserListPickerProps, catalogApiRef, catalogRouteRef, columnFactories, entityRoute, entityRouteParams, entityRouteRef, favoriteEntityIcon, favoriteEntityTooltip, formatEntityRefTitle, getEntityMetadataEditUrl, getEntityMetadataViewUrl, getEntityRelations, getEntitySourceLocation, isOwnerOf, loadCatalogOwnerRefs, loadIdentityOwnerRefs, reduceCatalogFilters, reduceEntityFilters, rootRoute, starredEntitiesApiRef, useEntity, useEntityCompoundName, useEntityFromUrl, useEntityKinds, useEntityListProvider, useEntityOwnership, useEntityPermission, useEntityTypeFilter, useOwnUser, useOwnedEntities, useRelatedEntities, useStarredEntities, useStarredEntity };