@backstage/plugin-home 0.5.8 → 0.5.9-next.1

package/dist/esm/{index-e7416f2d.esm.js → index-20932a73.esm.js}

@@ -1,8 +1,9 @@
 import React from 'react';
 import { useOutlet } from 'react-router-dom';
-export { CustomHomepageGrid } from '../index.esm.js';
+export { CustomHomepageGrid, VisitListener } from '../index.esm.js';
 import '@backstage/core-plugin-api';
 import '@backstage/plugin-home-react';
+import '@backstage/core-app-api';
 import 'react-grid-layout';
 import 'react-grid-layout/css/styles.css';
 import 'react-resizable/css/styles.css';
@@ -25,6 +26,7 @@ import '@material-ui/icons/Save';
 import '@material-ui/icons/Edit';
 import '@material-ui/icons/Cancel';
 import 'zod';
+import '@backstage/catalog-model';
 
 const HomepageCompositionRoot = (props) => {
   var _a;
@@ -34,4 +36,4 @@ const HomepageCompositionRoot = (props) => {
 };
 
 export { HomepageCompositionRoot };
-//# sourceMappingURL=index-e7416f2d.esm.js.map
+//# sourceMappingURL=index-20932a73.esm.js.map

package/dist/esm/{index-e7416f2d.esm.js.map → index-20932a73.esm.js.map}

@@ -1 +1 @@
-{"version":3,"file":"index-e7416f2d.esm.js","sources":["../../src/components/HomepageCompositionRoot.tsx"],"sourcesContent":["/*\n * Copyright 2021 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 React, { ReactNode } from 'react';\nimport { useOutlet } from 'react-router-dom';\n\nexport const HomepageCompositionRoot = (props: {\n  title?: string;\n  children?: ReactNode;\n}) => {\n  const outlet = useOutlet();\n  const children = props.children ?? outlet;\n  return <>{children}</>;\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmBa,MAAA,uBAAA,GAA0B,CAAC,KAGlC,KAAA;AAtBN,EAAA,IAAA,EAAA,CAAA;AAuBE,EAAA,MAAM,SAAS,SAAU,EAAA,CAAA;AACzB,EAAM,MAAA,QAAA,GAAA,CAAW,EAAM,GAAA,KAAA,CAAA,QAAA,KAAN,IAAkB,GAAA,EAAA,GAAA,MAAA,CAAA;AACnC,EAAA,iEAAU,QAAS,CAAA,CAAA;AACrB;;;;"}
+{"version":3,"file":"index-20932a73.esm.js","sources":["../../src/components/HomepageCompositionRoot.tsx"],"sourcesContent":["/*\n * Copyright 2021 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 React, { ReactNode } from 'react';\nimport { useOutlet } from 'react-router-dom';\n\nexport const HomepageCompositionRoot = (props: {\n  title?: string;\n  children?: ReactNode;\n}) => {\n  const outlet = useOutlet();\n  const children = props.children ?? outlet;\n  return <>{children}</>;\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmBa,MAAA,uBAAA,GAA0B,CAAC,KAGlC,KAAA;AAtBN,EAAA,IAAA,EAAA,CAAA;AAuBE,EAAA,MAAM,SAAS,SAAU,EAAA,CAAA;AACzB,EAAM,MAAA,QAAA,GAAA,CAAW,EAAM,GAAA,KAAA,CAAA,QAAA,KAAN,IAAkB,GAAA,EAAA,GAAA,MAAA,CAAA;AACnC,EAAA,iEAAU,QAAS,CAAA,CAAA;AACrB;;;;"}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { createCardExtension as createCardExtension$1, CardExtensionProps as Car
 import * as React from 'react';
 import React__default, { ReactNode, ReactElement } from 'react';
 import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
+import { StorageApi, IdentityApi, ErrorApi } from '@backstage/core-plugin-api';
 
 /** @public */
 type Tool = {
@@ -32,10 +33,118 @@ type WelcomeTitleLanguageProps = {
     language?: string[];
 };
 
+/**
+ * @public
+ * Model for a visit entity.
+ */
+type Visit = {
+    /**
+     * The auto-generated visit identification.
+     */
+    id: string;
+    /**
+     * The visited entity, usually an entity id.
+     */
+    name: string;
+    /**
+     * The visited url pathname, usually the entity route.
+     */
+    pathname: string;
+    /**
+     * An individual view count.
+     */
+    hits: number;
+    /**
+     * Last date and time of visit. Format: unix epoch in ms.
+     */
+    timestamp: number;
+    /**
+     * Optional entity reference. See stringifyEntityRef from catalog-model.
+     */
+    entityRef?: string;
+};
+/**
+ * @public
+ * This data structure represents the parameters associated with search queries for visits.
+ */
+type VisitsApiQueryParams = {
+    /**
+     * Limits the number of results returned. The default is 8.
+     */
+    limit?: number;
+    /**
+     * Allows ordering visits on entity properties.
+     * @example
+     * Sort ascending by the timestamp field.
+     * ```
+     * { orderBy: [{ field: 'timestamp', direction: 'asc' }] }
+     * ```
+     */
+    orderBy?: Array<{
+        field: keyof Visit;
+        direction: 'asc' | 'desc';
+    }>;
+    /**
+     * Allows filtering visits on entity properties.
+     * @example
+     * Most popular docs on the past 7 days
+     * ```
+     * {
+     *   orderBy: [{ field: 'hits', direction: 'desc' }],
+     *   filterBy: [
+     *     { field: 'timestamp', operator: '>=', value: <date> },
+     *     { field: 'entityRef', operator: 'contains', value: 'docs' }
+     *   ]
+     * }
+     * ```
+     */
+    filterBy?: Array<{
+        field: keyof Visit;
+        operator: '<' | '<=' | '==' | '!=' | '>' | '>=' | 'contains';
+        value: string | number;
+    }>;
+};
+/**
+ * @public
+ * This data structure represents the parameters associated with saving visits.
+ */
+type VisitsApiSaveParams = {
+    visit: Omit<Visit, 'id' | 'hits' | 'timestamp'>;
+};
+/**
+ * @public
+ * Visits API public contract.
+ */
+interface VisitsApi {
+    /**
+     * Persist a new visit.
+     * @param pageVisit - a new visit data
+     */
+    save(saveParams: VisitsApiSaveParams): Promise<Visit>;
+    /**
+     * Get user visits.
+     * @param queryParams - optional search query params.
+     */
+    list(queryParams?: VisitsApiQueryParams): Promise<Visit[]>;
+}
+/** @public */
+declare const visitsApiRef: _backstage_core_plugin_api.ApiRef<VisitsApi>;
+
+/** @public */
+type VisitedByTypeKind = 'recent' | 'top';
+/** @public */
+type VisitedByTypeProps = {
+    visits?: Array<Visit>;
+    numVisitsOpen?: number;
+    numVisitsTotal?: number;
+    loading?: boolean;
+    kind: VisitedByTypeKind;
+};
+
 /** @public */
 declare const homePlugin: _backstage_core_plugin_api.BackstagePlugin<{
     root: _backstage_core_plugin_api.RouteRef<undefined>;
-}, {}, {}>;
+}, {}>;
 /** @public */
 declare const HomepageCompositionRoot: (props: {
     title?: string | undefined;
@@ -104,6 +213,16 @@ declare const HeaderWorldClock: (props: {
     clockConfigs: ClockConfig[];
     customTimeFormat?: Intl.DateTimeFormatOptions | undefined;
 }) => React.JSX.Element | null;
+/**
+ * Display top visited pages for the homepage
+ * @public
+ */
+declare const HomePageTopVisited: (props: _backstage_plugin_home_react.CardExtensionProps<Partial<VisitedByTypeProps>>) => React.JSX.Element;
+/**
+ * Display recently visited pages for the homepage
+ * @public
+ */
+declare const HomePageRecentlyVisited: (props: _backstage_plugin_home_react.CardExtensionProps<Partial<VisitedByTypeProps>>) => React.JSX.Element;
 
 /**
  * Breakpoint options for <CustomHomepageGridProps/>
@@ -202,6 +321,21 @@ type LayoutConfiguration = {
  */
 declare const CustomHomepageGrid: (props: CustomHomepageGridProps) => React__default.JSX.Element;
 
+/**
+ * @public
+ * Component responsible for listening to location changes and calling
+ * the visitsApi to save visits.
+ */
+declare const VisitListener: ({ children, toEntityRef, visitName, }: {
+    children?: React__default.ReactNode;
+    toEntityRef?: (({ pathname }: {
+        pathname: string;
+    }) => string | undefined) | undefined;
+    visitName?: (({ pathname }: {
+        pathname: string;
+    }) => string) | undefined;
+}) => JSX.Element;
+
 /** @public */
 declare const TemplateBackstageLogo: (props: {
     classes: {
@@ -264,4 +398,50 @@ declare const SettingsModal: (props: {
     children: JSX.Element;
 }) => React.JSX.Element;
 
-export { Breakpoint, CardConfig, CardExtensionProps, CardLayout, CardSettings, ClockConfig, ComponentAccordion, ComponentParts, ComponentRenderer, ComponentTab, ComponentTabs, CustomHomepageGrid, CustomHomepageGridProps, HeaderWorldClock, HomePageCompanyLogo, HomePageRandomJoke, HomePageStarredEntities, HomePageToolkit, HomepageCompositionRoot, LayoutConfiguration, RendererProps, SettingsModal, TemplateBackstageLogo, TemplateBackstageLogoIcon, Tool, ToolkitContentProps, WelcomeTitle, WelcomeTitleLanguageProps, createCardExtension, homePlugin };
+/** @public */
+type VisitsStorageApiOptions = {
+    limit?: number;
+    storageApi: StorageApi;
+    identityApi: IdentityApi;
+};
+/**
+ * @public
+ * This is an implementation of VisitsApi that relies on a StorageApi.
+ * Beware that filtering and ordering are done in memory therefore it is
+ * prudent to keep limit to a reasonable size.
+ */
+declare class VisitsStorageApi implements VisitsApi {
+    private readonly limit;
+    private readonly storageApi;
+    private readonly storageKeyPrefix;
+    private readonly identityApi;
+    static create(options: VisitsStorageApiOptions): VisitsStorageApi;
+    private constructor();
+    /**
+     * Returns a list of visits through the visitsApi
+     */
+    list(queryParams?: VisitsApiQueryParams): Promise<Visit[]>;
+    /**
+     * Saves a visit through the visitsApi
+     */
+    save(saveParams: VisitsApiSaveParams): Promise<Visit>;
+    private persistAll;
+    private retrieveAll;
+    private compare;
+}
+
+/** @public */
+type VisitsWebStorageApiOptions = {
+    limit?: number;
+    identityApi: IdentityApi;
+    errorApi: ErrorApi;
+};
+/**
+ * @public
+ * This is a reference implementation of VisitsApi using WebStorage.
+ */
+declare class VisitsWebStorageApi {
+    static create(options: VisitsWebStorageApiOptions): VisitsStorageApi;
+}
+
+export { Breakpoint, CardConfig, CardExtensionProps, CardLayout, CardSettings, ClockConfig, ComponentAccordion, ComponentParts, ComponentRenderer, ComponentTab, ComponentTabs, CustomHomepageGrid, CustomHomepageGridProps, HeaderWorldClock, HomePageCompanyLogo, HomePageRandomJoke, HomePageRecentlyVisited, HomePageStarredEntities, HomePageToolkit, HomePageTopVisited, HomepageCompositionRoot, LayoutConfiguration, RendererProps, SettingsModal, TemplateBackstageLogo, TemplateBackstageLogoIcon, Tool, ToolkitContentProps, Visit, VisitListener, VisitedByTypeKind, VisitedByTypeProps, VisitsApi, VisitsApiQueryParams, VisitsApiSaveParams, VisitsStorageApi, VisitsStorageApiOptions, VisitsWebStorageApi, VisitsWebStorageApiOptions, WelcomeTitle, WelcomeTitleLanguageProps, createCardExtension, homePlugin, visitsApiRef };

package/dist/index.esm.js

@@ -1,7 +1,8 @@
-import { createRouteRef, createPlugin, createRoutableExtension, createComponentExtension, useElementFilter, useApi, storageApiRef, getComponentData } from '@backstage/core-plugin-api';
+import { createRouteRef, createApiRef, createPlugin, createApiFactory, storageApiRef, identityApiRef, createRoutableExtension, createComponentExtension, useElementFilter, useApi, getComponentData } from '@backstage/core-plugin-api';
 import { createCardExtension as createCardExtension$1, SettingsModal as SettingsModal$1 } from '@backstage/plugin-home-react';
-import React, { useCallback, useMemo } from 'react';
-import 'react-router-dom';
+import { WebStorage } from '@backstage/core-app-api';
+import React, { useCallback, useMemo, useEffect } from 'react';
+import { useLocation } from 'react-router-dom';
 import { WidthProvider, Responsive } from 'react-grid-layout';
 import 'react-grid-layout/css/styles.css';
 import 'react-resizable/css/styles.css';
@@ -24,13 +25,140 @@ import SaveIcon from '@material-ui/icons/Save';
 import EditIcon from '@material-ui/icons/Edit';
 import CancelIcon from '@material-ui/icons/Cancel';
 import { z } from 'zod';
+import { stringifyEntityRef } from '@backstage/catalog-model';
 
 const rootRouteRef = createRouteRef({
   id: "home"
 });
 
+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;
+};
+class VisitsStorageApi {
+  constructor(options) {
+    __publicField(this, "limit");
+    __publicField(this, "storageApi");
+    __publicField(this, "storageKeyPrefix", "@backstage/plugin-home:visits");
+    __publicField(this, "identityApi");
+    var _a;
+    this.limit = Math.abs((_a = options.limit) != null ? _a : 100);
+    this.storageApi = options.storageApi;
+    this.identityApi = options.identityApi;
+  }
+  static create(options) {
+    return new VisitsStorageApi(options);
+  }
+  /**
+   * Returns a list of visits through the visitsApi
+   */
+  async list(queryParams) {
+    var _a, _b;
+    let visits = [...await this.retrieveAll()];
+    ((_a = queryParams == null ? void 0 : queryParams.orderBy) != null ? _a : []).reverse().forEach((order) => {
+      if (order.direction === "asc") {
+        visits.sort((a, b) => this.compare(order, a, b));
+      } else {
+        visits.sort((a, b) => this.compare(order, b, a));
+      }
+    });
+    ((_b = queryParams == null ? void 0 : queryParams.filterBy) != null ? _b : []).reverse().forEach((filter) => {
+      visits = visits.filter((visit) => {
+        const field = visit[filter.field];
+        if (filter.operator === ">")
+          return field > filter.value;
+        if (filter.operator === ">=")
+          return field >= filter.value;
+        if (filter.operator === "<")
+          return field < filter.value;
+        if (filter.operator === "<=")
+          return field <= filter.value;
+        if (filter.operator === "==")
+          return field === filter.value;
+        if (filter.operator === "!=")
+          return field !== filter.value;
+        if (filter.operator === "contains")
+          return `${field}`.includes(`${filter.value}`);
+        return false;
+      });
+    });
+    return visits;
+  }
+  /**
+   * Saves a visit through the visitsApi
+   */
+  async save(saveParams) {
+    const visits = [...await this.retrieveAll()];
+    const visit = {
+      ...saveParams.visit,
+      id: window.crypto.randomUUID(),
+      hits: 1,
+      timestamp: Date.now()
+    };
+    const visitIndex = visits.findIndex((e) => e.pathname === visit.pathname);
+    if (visitIndex >= 0) {
+      visit.id = visits[visitIndex].id;
+      visit.hits = visits[visitIndex].hits + 1;
+      visits[visitIndex] = visit;
+    } else {
+      visits.push(visit);
+    }
+    visits.sort((a, b) => b.timestamp - a.timestamp);
+    await this.persistAll(visits.splice(0, this.limit));
+    return visit;
+  }
+  async persistAll(visits) {
+    const { userEntityRef } = await this.identityApi.getBackstageIdentity();
+    const storageKey = `${this.storageKeyPrefix}:${userEntityRef}`;
+    return this.storageApi.set(storageKey, visits);
+  }
+  async retrieveAll() {
+    var _a;
+    const { userEntityRef } = await this.identityApi.getBackstageIdentity();
+    const storageKey = `${this.storageKeyPrefix}:${userEntityRef}`;
+    let visits;
+    try {
+      visits = (_a = this.storageApi.snapshot(storageKey).value) != null ? _a : [];
+    } catch {
+      visits = [];
+    }
+    return visits;
+  }
+  // This assumes Visit fields are either numbers or strings
+  compare(order, a, b) {
+    const isNumber = typeof a[order.field] === "number";
+    return isNumber ? a[order.field] - b[order.field] : `${a[order.field]}`.localeCompare(`${b[order.field]}`);
+  }
+}
+
+class VisitsWebStorageApi {
+  static create(options) {
+    return VisitsStorageApi.create({
+      limit: options.limit,
+      identityApi: options.identityApi,
+      storageApi: WebStorage.create({ errorApi: options.errorApi })
+    });
+  }
+}
+
+const visitsApiRef = createApiRef({
+  id: "homepage.visits"
+});
+
 const homePlugin = createPlugin({
   id: "home",
+  apis: [
+    createApiFactory({
+      api: visitsApiRef,
+      deps: {
+        storageApi: storageApiRef,
+        identityApi: identityApiRef
+      },
+      factory: ({ storageApi, identityApi }) => VisitsStorageApi.create({ storageApi, identityApi })
+    })
+  ],
   routes: {
     root: rootRouteRef
   }
@@ -38,7 +166,7 @@ const homePlugin = createPlugin({
 const HomepageCompositionRoot = homePlugin.provide(
   createRoutableExtension({
     name: "HomepageCompositionRoot",
-    component: () => import('./esm/index-e7416f2d.esm.js').then((m) => m.HomepageCompositionRoot),
+    component: () => import('./esm/index-20932a73.esm.js').then((m) => m.HomepageCompositionRoot),
     mountPoint: rootRouteRef
   })
 );
@@ -132,6 +260,18 @@ const HeaderWorldClock = homePlugin.provide(
     }
   })
 );
+const HomePageTopVisited = homePlugin.provide(
+  createCardExtension$1({
+    name: "HomePageTopVisited",
+    components: () => import('./esm/TopVisited-918c6b5f.esm.js')
+  })
+);
+const HomePageRecentlyVisited = homePlugin.provide(
+  createCardExtension$1({
+    name: "HomePageRecentlyVisited",
+    components: () => import('./esm/RecentlyVisited-618bf2be.esm.js')
+  })
+);
 
 const Form = withTheme(require("@rjsf/material-ui-v5").Theme);
 const useStyles$3 = makeStyles(
@@ -658,6 +798,59 @@ const CustomHomepageGrid = (props) => {
   ));
 };
 
+const getToEntityRef = ({
+  rootPath = "catalog",
+  stringifyEntityRefImpl = stringifyEntityRef
+} = {}) => ({ pathname }) => {
+  const regex = new RegExp(
+    `^/${rootPath}/(?<namespace>[^/]+)/(?<kind>[^/]+)/(?<name>[^/]+)`
+  );
+  const result = regex.exec(pathname);
+  if (!result || !(result == null ? void 0 : result.groups))
+    return void 0;
+  const entity = {
+    namespace: result.groups.namespace,
+    kind: result.groups.kind,
+    name: result.groups.name
+  };
+  return stringifyEntityRefImpl(entity);
+};
+const getVisitName = ({ rootPath = "catalog", document = global.document } = {}) => ({ pathname }) => {
+  const regex = new RegExp(
+    `^/${rootPath}/(?<namespace>[^/]+)/(?<kind>[^/]+)/(?<name>[^/]+)`
+  );
+  let result = regex.exec(pathname);
+  if (result && (result == null ? void 0 : result.groups))
+    return result.groups.name;
+  result = /^\/(?<name>[^\/]+)$/.exec(pathname);
+  if (result && (result == null ? void 0 : result.groups))
+    return result.groups.name;
+  return document.title;
+};
+const VisitListener = ({
+  children,
+  toEntityRef,
+  visitName
+}) => {
+  const visitsApi = useApi(visitsApiRef);
+  const { pathname } = useLocation();
+  const toEntityRefImpl = toEntityRef != null ? toEntityRef : getToEntityRef();
+  const visitNameImpl = visitName != null ? visitName : getVisitName();
+  useEffect(() => {
+    const requestId = requestAnimationFrame(() => {
+      visitsApi.save({
+        visit: {
+          name: visitNameImpl({ pathname }),
+          pathname,
+          entityRef: toEntityRefImpl({ pathname })
+        }
+      });
+    });
+    return () => cancelAnimationFrame(requestId);
+  }, [visitsApi, pathname, toEntityRefImpl, visitNameImpl]);
+  return /* @__PURE__ */ React.createElement(React.Fragment, null, children);
+};
+
 const TemplateBackstageLogo = (props) => {
   return /* @__PURE__ */ React.createElement(
     "svg",
@@ -707,5 +900,5 @@ const TemplateBackstageLogoIcon = () => {
 const createCardExtension = createCardExtension$1;
 const SettingsModal = SettingsModal$1;
 
-export { ComponentAccordion, ComponentTab, ComponentTabs, CustomHomepageGrid, HeaderWorldClock, HomePageCompanyLogo, HomePageRandomJoke, HomePageStarredEntities, HomePageToolkit, HomepageCompositionRoot, SettingsModal, TemplateBackstageLogo, TemplateBackstageLogoIcon, WelcomeTitle, createCardExtension, homePlugin };
+export { ComponentAccordion, ComponentTab, ComponentTabs, CustomHomepageGrid, HeaderWorldClock, HomePageCompanyLogo, HomePageRandomJoke, HomePageRecentlyVisited, HomePageStarredEntities, HomePageToolkit, HomePageTopVisited, HomepageCompositionRoot, SettingsModal, TemplateBackstageLogo, TemplateBackstageLogoIcon, VisitListener, VisitsStorageApi, VisitsWebStorageApi, WelcomeTitle, createCardExtension, homePlugin, visitsApiRef };
 //# sourceMappingURL=index.esm.js.map