@backstage/plugin-techdocs 0.13.3 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # @backstage/plugin-techdocs
 
+## 0.15.0
+
+### Minor Changes
+
+- ee3d6c6f10: **BREAKING:**
+  Table column utilities `createNameColumn`, `createOwnerColumn`, `createTypeColumn` as well as actions utilities `createCopyDocsUrlAction` and `createStarEntityAction` are no longer directly exported. Instead accessible through DocsTable and EntityListDocsTable.
+
+  Use as following:
+
+  ```tsx
+  DocsTable.columns.createNameColumn();
+  DocsTable.columns.createOwnerColumn();
+  DocsTable.columns.createTypeColumn();
+
+  DocsTable.actions.createCopyDocsUrlAction();
+  DocsTable.actions.createStarEntityAction();
+  ```
+
+  - Renamed `DocsResultListItem` to `TechDocsSearchResultListItem`, leaving the old name in place as a deprecations.
+
+  - Renamed `TechDocsPage` to `TechDocsReaderPage`, leaving the old name in place as a deprecations.
+
+  - Renamed `TechDocsPageRenderFunction` to `TechDocsPageRenderFunction`, leaving the old name in place as a deprecations.
+
+  - Renamed `TechDocsPageHeader` to `TechDocsReaderPageHeader`, leaving the old name in place as a deprecations.
+
+  - `LegacyTechDocsHome` marked as deprecated and will be deleted in next release, use `TechDocsCustomHome` instead.
+
+  - `LegacyTechDocsPage` marked as deprecated and will be deleted in next release, use `TechDocsReaderPage` instead.
+
+### Patch Changes
+
+- 64b430f80d: chore(deps): bump `react-text-truncate` from 0.17.0 to 0.18.0
+- 899f196af5: Use `getEntityByRef` instead of `getEntityByName` in the catalog client
+- f41a293231: - **DEPRECATION**: Deprecated `formatEntityRefTitle` in favor of the new `humanizeEntityRef` method instead. Please migrate to using the new method instead.
+- c5fda066b1: Collapse techdocs sidebar on small devices
+- f590d1681b: Removed usage of deprecated favorite utility methods.
+- 5b0f9a75fa: Remove copyright from old footer in documentation generated with previous version of `mkdocs-techdocs-plugin` (`v0.2.2`).
+- 0c3ba547a6: Show feedback when copying code snippet to clipboard.
+- 0ca964ee0e: Fixed a bug that could cause searches in the in-context TechDocs search bar to show results from a different TechDocs site.
+- 36aa63022b: Use `CompoundEntityRef` instead of `EntityName`, and `getCompoundEntityRef` instead of `getEntityName`, from `@backstage/catalog-model`.
+- Updated dependencies
+  - @backstage/catalog-model@0.12.0
+  - @backstage/core-components@0.9.0
+  - @backstage/plugin-search@0.7.2
+  - @backstage/plugin-catalog@0.9.1
+  - @backstage/plugin-catalog-react@0.8.0
+  - @backstage/integration@0.8.0
+  - @backstage/core-plugin-api@0.8.0
+  - @backstage/integration-react@0.1.24
+
+## 0.14.0
+
+### Minor Changes
+
+- 2262fe19c9: **BREAKING**: Removed support for passing in an explicit `entity` prop to entity page extensions, which has been deprecated for a long time. This is only a breaking change at the TypeScript level, as this property was already ignored.
+- 4faae902eb: Adjust the Tech Docs page theme as a side effect of the `mkdocs-material` theme update.
+
+  If you use the `spofify/techdocs` image to build your documentation, make sure you use version `spotify/techdocs:v0.3.7`.
+
+  **Breaking**: The `PyMdown` extensions have also been updated and some syntax may have changed, so it is recommended that you check the extension's documentation if something stops working.
+  For example, the syntax of tags below was deprecated in `PyMdown` extensions `v.7.0` and in `v.8.0.0` it has been removed. This means that the old syntax specified below no longer works.
+
+  ````markdown
+  ```markdown tab="tab"
+  This is some markdown
+  ```
+
+  ```markdown tab="tab 2"
+  This is some markdown in tab 2
+  ```
+  ````
+
+### Patch Changes
+
+- 3bbb4d98c6: Changed <TechdocsPage /> to use <NotFoundErrorPage /> from createApp
+- ed09ad8093: Updated usage of the `LocationSpec` type from `@backstage/catalog-model`, which is deprecated.
+- b776ce5aab: Replaced use of deprecated `useEntityListProvider` hook with `useEntityList`.
+- d4f67fa728: Removed import of deprecated hook.
+- 45e1706328: Continuation of [#9569](https://github.com/backstage/backstage/pull/9569), fix Tech Docs Reader search position to be the same width as content.
+- 919cf2f836: Minor updates to match the new `targetRef` field of relations, and to stop consuming the `target` field
+- Updated dependencies
+  - @backstage/plugin-catalog@0.9.0
+  - @backstage/core-components@0.8.10
+  - @backstage/plugin-catalog-react@0.7.0
+  - @backstage/catalog-model@0.11.0
+  - @backstage/core-plugin-api@0.7.0
+  - @backstage/integration@0.7.5
+  - @backstage/plugin-search@0.7.1
+  - @backstage/integration-react@0.1.23
+
+## 0.13.4
+
+### Patch Changes
+
+- 1ed305728b: Bump `node-fetch` to version 2.6.7 and `cross-fetch` to version 3.1.5
+- c77c5c7eb6: Added `backstage.role` to `package.json`
+- 6553985cd4: Match text size of admonitions to main content text size.
+- 9df7b43e1a: Improve overall appearance of highlighted code in docs.
+- Updated dependencies
+  - @backstage/core-components@0.8.9
+  - @backstage/core-plugin-api@0.6.1
+  - @backstage/errors@0.2.1
+  - @backstage/integration@0.7.3
+  - @backstage/integration-react@0.1.22
+  - @backstage/plugin-catalog@0.8.0
+  - @backstage/plugin-catalog-react@0.6.15
+  - @backstage/plugin-search@0.7.0
+  - @backstage/catalog-model@0.10.0
+  - @backstage/config@0.1.14
+  - @backstage/theme@0.2.15
+
 ## 0.13.3
 
 ### Patch Changes

package/dist/esm/TechDocsCustomHome-4e5e8594.esm.js

@@ -0,0 +1,143 @@
+import React, { useState } from 'react';
+import useAsync from 'react-use/lib/useAsync';
+import { makeStyles } from '@material-ui/core';
+import { catalogApiRef, CATALOG_FILTER_EXISTS, isOwnerOf } from '@backstage/plugin-catalog-react';
+import { parseEntityRef, DEFAULT_NAMESPACE } from '@backstage/catalog-model';
+import { TechDocsPageWrapper, DocsTable, DocsCardGrid } from '../index.esm.js';
+import { Content, Progress, WarningPanel, CodeSnippet, HeaderTabs, ContentHeader, SupportButton } from '@backstage/core-components';
+import { useApi, identityApiRef } from '@backstage/core-plugin-api';
+import '@backstage/errors';
+import 'event-source-polyfill';
+import 'react-router-dom';
+import '@backstage/integration-react';
+import '@backstage/integration';
+import '@material-ui/icons/FeedbackOutlined';
+import 'react-dom';
+import 'git-url-parse';
+import '@material-ui/icons/Menu';
+import 'dompurify';
+import 'react-text-truncate';
+import '@backstage/plugin-search';
+import '@material-ui/icons/Search';
+import '@material-ui/lab/Autocomplete';
+import 'react-router';
+import 'react-use/lib/useDebounce';
+import '@material-ui/lab';
+import '@material-ui/icons/Close';
+import 'react-use/lib/useAsyncRetry';
+import '@material-ui/icons/Code';
+import 'react-use/lib/useCopyToClipboard';
+import 'lodash';
+import '@material-ui/icons/Share';
+import '@material-ui/styles';
+import '@material-ui/icons/Star';
+import '@material-ui/icons/StarBorder';
+import '@backstage/plugin-catalog';
+
+const panels = {
+  DocsTable,
+  DocsCardGrid
+};
+const CustomPanel = ({
+  config,
+  entities,
+  index
+}) => {
+  const useStyles = makeStyles({
+    panelContainer: {
+      marginBottom: "2rem",
+      ...config.panelCSS ? config.panelCSS : {}
+    }
+  });
+  const classes = useStyles();
+  const { value: user } = useOwnUser();
+  const Panel = panels[config.panelType];
+  const shownEntities = entities.filter((entity) => {
+    if (config.filterPredicate === "ownedByUser") {
+      if (!user) {
+        return false;
+      }
+      return isOwnerOf(user, entity);
+    }
+    return typeof config.filterPredicate === "function" && config.filterPredicate(entity);
+  });
+  return /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement(ContentHeader, {
+    title: config.title,
+    description: config.description
+  }, index === 0 ? /* @__PURE__ */ React.createElement(SupportButton, null, "Discover documentation in your ecosystem.") : null), /* @__PURE__ */ React.createElement("div", {
+    className: classes.panelContainer
+  }, /* @__PURE__ */ React.createElement(Panel, {
+    "data-testid": "techdocs-custom-panel",
+    entities: shownEntities
+  })));
+};
+const TechDocsCustomHome = (props) => {
+  const { tabsConfig } = props;
+  const [selectedTab, setSelectedTab] = useState(0);
+  const catalogApi = useApi(catalogApiRef);
+  const {
+    value: entities,
+    loading,
+    error
+  } = useAsync(async () => {
+    const response = await catalogApi.getEntities({
+      filter: {
+        "metadata.annotations.backstage.io/techdocs-ref": CATALOG_FILTER_EXISTS
+      },
+      fields: [
+        "apiVersion",
+        "kind",
+        "metadata",
+        "relations",
+        "spec.owner",
+        "spec.type"
+      ]
+    });
+    return response.items.filter((entity) => {
+      var _a;
+      return !!((_a = entity.metadata.annotations) == null ? void 0 : _a["backstage.io/techdocs-ref"]);
+    });
+  });
+  const currentTabConfig = tabsConfig[selectedTab];
+  if (loading) {
+    return /* @__PURE__ */ React.createElement(TechDocsPageWrapper, null, /* @__PURE__ */ React.createElement(Content, null, /* @__PURE__ */ React.createElement(Progress, null)));
+  }
+  if (error) {
+    return /* @__PURE__ */ React.createElement(TechDocsPageWrapper, null, /* @__PURE__ */ React.createElement(Content, null, /* @__PURE__ */ React.createElement(WarningPanel, {
+      severity: "error",
+      title: "Could not load available documentation."
+    }, /* @__PURE__ */ React.createElement(CodeSnippet, {
+      language: "text",
+      text: error.toString()
+    }))));
+  }
+  return /* @__PURE__ */ React.createElement(TechDocsPageWrapper, null, /* @__PURE__ */ React.createElement(HeaderTabs, {
+    selectedIndex: selectedTab,
+    onChange: (index) => setSelectedTab(index),
+    tabs: tabsConfig.map(({ label }, index) => ({
+      id: index.toString(),
+      label
+    }))
+  }), /* @__PURE__ */ React.createElement(Content, {
+    "data-testid": "techdocs-content"
+  }, currentTabConfig.panels.map((config, index) => /* @__PURE__ */ React.createElement(CustomPanel, {
+    key: index,
+    config,
+    entities: !!entities ? entities : [],
+    index
+  }))));
+};
+function useOwnUser() {
+  const catalogApi = useApi(catalogApiRef);
+  const identityApi = useApi(identityApiRef);
+  return useAsync(async () => {
+    const identity = await identityApi.getBackstageIdentity();
+    return catalogApi.getEntityByRef(parseEntityRef(identity.userEntityRef, {
+      defaultKind: "User",
+      defaultNamespace: DEFAULT_NAMESPACE
+    }));
+  }, [catalogApi, identityApi]);
+}
+
+export { TechDocsCustomHome };
+//# sourceMappingURL=TechDocsCustomHome-4e5e8594.esm.js.map

package/dist/esm/TechDocsCustomHome-4e5e8594.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TechDocsCustomHome-4e5e8594.esm.js","sources":["../../src/home/components/TechDocsCustomHome.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, { useState } from 'react';\nimport useAsync, { AsyncState } from 'react-use/lib/useAsync';\nimport { makeStyles } from '@material-ui/core';\nimport { CSSProperties } from '@material-ui/styles';\nimport {\n  CATALOG_FILTER_EXISTS,\n  catalogApiRef,\n  CatalogApi,\n  isOwnerOf,\n} from '@backstage/plugin-catalog-react';\nimport {\n  DEFAULT_NAMESPACE,\n  Entity,\n  parseEntityRef,\n  UserEntity,\n} from '@backstage/catalog-model';\nimport { DocsTable } from './Tables';\nimport { DocsCardGrid } from './Grids';\nimport { TechDocsPageWrapper } from './TechDocsPageWrapper';\n\nimport {\n  CodeSnippet,\n  Content,\n  HeaderTabs,\n  Progress,\n  WarningPanel,\n  SupportButton,\n  ContentHeader,\n} from '@backstage/core-components';\n\nimport { identityApiRef, useApi } from '@backstage/core-plugin-api';\n\nconst panels = {\n  DocsTable: DocsTable,\n  DocsCardGrid: DocsCardGrid,\n};\n\n/**\n * Available panel types\n *\n * @public\n */\nexport type PanelType = 'DocsCardGrid' | 'DocsTable';\n\n/**\n * Type representing a TechDocsCustomHome panel.\n *\n * @public\n */\nexport interface PanelConfig {\n  title: string;\n  description: string;\n  panelType: PanelType;\n  panelCSS?: CSSProperties;\n  filterPredicate: ((entity: Entity) => boolean) | string;\n}\n\n/**\n * Type representing a TechDocsCustomHome tab.\n *\n * @public\n */\nexport interface TabConfig {\n  label: string;\n  panels: PanelConfig[];\n}\n\n/**\n * Type representing a list of TechDocsCustomHome tabs.\n *\n * @public\n */\nexport type TabsConfig = TabConfig[];\n\nconst CustomPanel = ({\n  config,\n  entities,\n  index,\n}: {\n  config: PanelConfig;\n  entities: Entity[];\n  index: number;\n}) => {\n  const useStyles = makeStyles({\n    panelContainer: {\n      marginBottom: '2rem',\n      ...(config.panelCSS ? config.panelCSS : {}),\n    },\n  });\n  const classes = useStyles();\n  const { value: user } = useOwnUser();\n\n  const Panel = panels[config.panelType];\n\n  const shownEntities = entities.filter(entity => {\n    if (config.filterPredicate === 'ownedByUser') {\n      if (!user) {\n        return false;\n      }\n      return isOwnerOf(user, entity);\n    }\n\n    return (\n      typeof config.filterPredicate === 'function' &&\n      config.filterPredicate(entity)\n    );\n  });\n\n  return (\n    <>\n      <ContentHeader title={config.title} description={config.description}>\n        {index === 0 ? (\n          <SupportButton>\n            Discover documentation in your ecosystem.\n          </SupportButton>\n        ) : null}\n      </ContentHeader>\n      <div className={classes.panelContainer}>\n        <Panel data-testid=\"techdocs-custom-panel\" entities={shownEntities} />\n      </div>\n    </>\n  );\n};\n\n/**\n * Props for {@link TechDocsCustomHome}\n *\n * @public\n */\nexport type TechDocsCustomHomeProps = {\n  tabsConfig: TabsConfig;\n};\n\nexport const TechDocsCustomHome = (props: TechDocsCustomHomeProps) => {\n  const { tabsConfig } = props;\n  const [selectedTab, setSelectedTab] = useState<number>(0);\n  const catalogApi: CatalogApi = useApi(catalogApiRef);\n\n  const {\n    value: entities,\n    loading,\n    error,\n  } = useAsync(async () => {\n    const response = await catalogApi.getEntities({\n      filter: {\n        'metadata.annotations.backstage.io/techdocs-ref': CATALOG_FILTER_EXISTS,\n      },\n      fields: [\n        'apiVersion',\n        'kind',\n        'metadata',\n        'relations',\n        'spec.owner',\n        'spec.type',\n      ],\n    });\n    return response.items.filter((entity: Entity) => {\n      return !!entity.metadata.annotations?.['backstage.io/techdocs-ref'];\n    });\n  });\n\n  const currentTabConfig = tabsConfig[selectedTab];\n\n  if (loading) {\n    return (\n      <TechDocsPageWrapper>\n        <Content>\n          <Progress />\n        </Content>\n      </TechDocsPageWrapper>\n    );\n  }\n\n  if (error) {\n    return (\n      <TechDocsPageWrapper>\n        <Content>\n          <WarningPanel\n            severity=\"error\"\n            title=\"Could not load available documentation.\"\n          >\n            <CodeSnippet language=\"text\" text={error.toString()} />\n          </WarningPanel>\n        </Content>\n      </TechDocsPageWrapper>\n    );\n  }\n\n  return (\n    <TechDocsPageWrapper>\n      <HeaderTabs\n        selectedIndex={selectedTab}\n        onChange={index => setSelectedTab(index)}\n        tabs={tabsConfig.map(({ label }, index) => ({\n          id: index.toString(),\n          label,\n        }))}\n      />\n      <Content data-testid=\"techdocs-content\">\n        {currentTabConfig.panels.map((config, index) => (\n          <CustomPanel\n            key={index}\n            config={config}\n            entities={!!entities ? entities : []}\n            index={index}\n          />\n        ))}\n      </Content>\n    </TechDocsPageWrapper>\n  );\n};\n\nfunction useOwnUser(): AsyncState<UserEntity | undefined> {\n  const catalogApi = useApi(catalogApiRef);\n  const identityApi = useApi(identityApiRef);\n\n  return useAsync(async () => {\n    const identity = await identityApi.getBackstageIdentity();\n    // TODO(freben): Defensively parse with defaults even though getEntityByRef\n    // supports the string form, since some auth resolvers have been known to\n    // return incomplete refs (just the name part) historically. This can be\n    // simplified in the future to just pass the ref immediately to\n    // getEntityByRef.\n    return catalogApi.getEntityByRef(\n      parseEntityRef(identity.userEntityRef, {\n        defaultKind: 'User',\n        defaultNamespace: DEFAULT_NAMESPACE,\n      }),\n    ) as Promise<UserEntity | undefined>;\n  }, [catalogApi, identityApi]);\n}\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,MAAM,SAAS;AAAA,EACb;AAAA,EACA;AAAA;AAwCF,MAAM,cAAc,CAAC;AAAA,EACnB;AAAA,EACA;AAAA,EACA;AAAA,MAKI;AACJ,QAAM,YAAY,WAAW;AAAA,IAC3B,gBAAgB;AAAA,MACd,cAAc;AAAA,SACV,OAAO,WAAW,OAAO,WAAW;AAAA;AAAA;AAG5C,QAAM,UAAU;AAChB,QAAM,EAAE,OAAO,SAAS;AAExB,QAAM,QAAQ,OAAO,OAAO;AAE5B,QAAM,gBAAgB,SAAS,OAAO,YAAU;AAC9C,QAAI,OAAO,oBAAoB,eAAe;AAC5C,UAAI,CAAC,MAAM;AACT,eAAO;AAAA;AAET,aAAO,UAAU,MAAM;AAAA;AAGzB,WACE,OAAO,OAAO,oBAAoB,cAClC,OAAO,gBAAgB;AAAA;AAI3B,uGAEK,eAAD;AAAA,IAAe,OAAO,OAAO;AAAA,IAAO,aAAa,OAAO;AAAA,KACrD,UAAU,wCACR,eAAD,MAAe,+CAGb,2CAEL,OAAD;AAAA,IAAK,WAAW,QAAQ;AAAA,yCACrB,OAAD;AAAA,IAAO,eAAY;AAAA,IAAwB,UAAU;AAAA;AAAA;MAehD,qBAAqB,CAAC,UAAmC;AACpE,QAAM,EAAE,eAAe;AACvB,QAAM,CAAC,aAAa,kBAAkB,SAAiB;AACvD,QAAM,aAAyB,OAAO;AAEtC,QAAM;AAAA,IACJ,OAAO;AAAA,IACP;AAAA,IACA;AAAA,MACE,SAAS,YAAY;AACvB,UAAM,WAAW,MAAM,WAAW,YAAY;AAAA,MAC5C,QAAQ;AAAA,QACN,kDAAkD;AAAA;AAAA,MAEpD,QAAQ;AAAA,QACN;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA;AAAA;AAGJ,WAAO,SAAS,MAAM,OAAO,CAAC,WAAmB;AA5KrD;AA6KM,aAAO,CAAC,eAAQ,SAAS,gBAAhB,mBAA8B;AAAA;AAAA;AAI3C,QAAM,mBAAmB,WAAW;AAEpC,MAAI,SAAS;AACX,+CACG,qBAAD,0CACG,SAAD,0CACG,UAAD;AAAA;AAMR,MAAI,OAAO;AACT,+CACG,qBAAD,0CACG,SAAD,0CACG,cAAD;AAAA,MACE,UAAS;AAAA,MACT,OAAM;AAAA,2CAEL,aAAD;AAAA,MAAa,UAAS;AAAA,MAAO,MAAM,MAAM;AAAA;AAAA;AAOnD,6CACG,qBAAD,0CACG,YAAD;AAAA,IACE,eAAe;AAAA,IACf,UAAU,WAAS,eAAe;AAAA,IAClC,MAAM,WAAW,IAAI,CAAC,EAAE,SAAS;AAAW,MAC1C,IAAI,MAAM;AAAA,MACV;AAAA;AAAA,0CAGH,SAAD;AAAA,IAAS,eAAY;AAAA,KAClB,iBAAiB,OAAO,IAAI,CAAC,QAAQ,8CACnC,aAAD;AAAA,IACE,KAAK;AAAA,IACL;AAAA,IACA,UAAU,CAAC,CAAC,WAAW,WAAW;AAAA,IAClC;AAAA;AAAA;AAQZ,sBAA0D;AACxD,QAAM,aAAa,OAAO;AAC1B,QAAM,cAAc,OAAO;AAE3B,SAAO,SAAS,YAAY;AAC1B,UAAM,WAAW,MAAM,YAAY;AAMnC,WAAO,WAAW,eAChB,eAAe,SAAS,eAAe;AAAA,MACrC,aAAa;AAAA,MACb,kBAAkB;AAAA;AAAA,KAGrB,CAAC,YAAY;AAAA;;;;"}