feat: add TechDocs addon LightBox

Signed-off-by: David Weber <david.weber@w3tec.ch>

.changeset/silver-badgers-heal.md

@@ -0,0 +1,35 @@
+---
+'@backstage/plugin-techdocs-module-addons-contrib': patch
+'@backstage/plugin-techdocs': patch
+---
+
+Create a TechDocs `<LightBox/>` addon that allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page.
+
+Here's an example on how to use it in a Backstage app:
+
+```diff
+import {
+  DefaultTechDocsHome,
+  TechDocsIndexPage,
+  TechDocsReaderPage,
+} from '@backstage/plugin-techdocs';
+import { TechDocsAddons } from '@backstage/plugin-techdocs-react/alpha';
++import { LightBox } from '@backstage/plugin-techdocs-module-addons-contrib';
+
+const AppRoutes = () => {
+  <FlatRoutes>
+    // other plugin routes
+    <Route path="/docs" element={<TechDocsIndexPage />}>
+      <DefaultTechDocsHome />
+    </Route>
+    <Route
+      path="/docs/:namespace/:kind/:name/*"
+      element={<TechDocsReaderPage />}
+    >
+      <TechDocsAddons>
++       <LightBox />
+      </TechDocsAddons>
+    </Route>
+  </FlatRoutes>;
+};
+```

docs/features/techdocs/addons.md

@@ -125,6 +125,7 @@ discover available Addons, we've compiled a list of them here:
 | [`<ExpandableNavigation />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.expandablenavigation) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to expand or collapse the entire TechDocs main navigation, and keeps the user's preferred state between documentation sites.                                                                                                                                                      |
 | [`<ReportIssue />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.reportissue)                   | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template.                                                            |
 | [`<TextSize />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.textsize)                         | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. |
+| [`<LightBox />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.lightbox)                         | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page. The image size of the light-box image is the same as the image size on the document page.                                                     |
 
 Got an Addon to contribute? Feel free to add a row above!
 

packages/app/src/App.tsx

@@ -78,6 +78,7 @@ import {
   ExpandableNavigation,
   ReportIssue,
   TextSize,
+  LightBox,
 } from '@backstage/plugin-techdocs-module-addons-contrib';
 import {
   SettingsLayout,
@@ -203,6 +204,7 @@ const routes = (
         <ExpandableNavigation />
         <ReportIssue />
         <TextSize />
+        <LightBox />
       </TechDocsAddons>
     </Route>
     <Route

packages/app/src/components/catalog/EntityPage.tsx

@@ -154,6 +154,7 @@ import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
 import {
   TextSize,
   ReportIssue,
+  LightBox,
 } from '@backstage/plugin-techdocs-module-addons-contrib';
 import { EntityCostInsightsContent } from '@backstage/plugin-cost-insights';
 
@@ -205,6 +206,7 @@ const techdocsContent = (
     <TechDocsAddons>
       <TextSize />
       <ReportIssue />
+      <LightBox />
     </TechDocsAddons>
   </EntityTechdocsContent>
 );

plugins/techdocs-module-addons-contrib/api-report.md

@@ -10,6 +10,9 @@ import { BackstagePlugin } from '@backstage/core-plugin-api';
 // @public
 export const ExpandableNavigation: () => JSX.Element | null;
 
+// @public
+export const LightBox: () => JSX.Element | null;
+
 // @public
 export const ReportIssue: (props: ReportIssueProps) => JSX.Element | null;
 

plugins/techdocs-module-addons-contrib/package.json

@@ -44,6 +44,7 @@
     "@material-ui/lab": "4.0.0-alpha.57",
     "@react-hookz/web": "^20.0.0",
     "git-url-parse": "^13.0.0",
+    "photoswipe": "^5.3.5",
     "react-use": "^17.2.4"
   },
   "peerDependencies": {

plugins/techdocs-module-addons-contrib/src/LigthBox/LightBox.test.tsx

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { TechDocsAddonTester } from '@backstage/plugin-techdocs-addons-test-utils';
+
+import React from 'react';
+
+import { LightBox } from '../plugin';
+
+describe('LightBox', () => {
+  it('renders without exploding', async () => {
+    const { getByText } = await TechDocsAddonTester.buildAddonsInTechDocs([
+      <LightBox />,
+    ])
+      .withDom(<body>TEST_CONTENT</body>)
+      .renderWithEffects();
+
+    expect(getByText('TEST_CONTENT')).toBeInTheDocument();
+  });
+
+  it('Add onclick event to images', async () => {
+    const { getByTestId } = await TechDocsAddonTester.buildAddonsInTechDocs([
+      <LightBox />,
+    ])
+      .withDom(
+        <img
+          data-testid="fixture"
+          src="http://example.com/dog.jpg"
+          alt="dog"
+        />,
+      )
+      .renderWithEffects();
+
+    expect(getByTestId('fixture').onclick).not.toBeUndefined();
+    expect(getByTestId('fixture').onclick).toEqual(expect.any(Function));
+  });
+});

plugins/techdocs-module-addons-contrib/src/LigthBox/LightBox.tsx

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { useEffect } from 'react';
+import { useShadowRootElements } from '@backstage/plugin-techdocs-react';
+// @ts-ignore
+import PhotoSwipeLightbox, { DataSource } from 'photoswipe/lightbox';
+import PhotoSwipe from 'photoswipe';
+import 'photoswipe/style.css';
+import './lightbox.css';
+
+export const LightBoxAddon = () => {
+  const images = useShadowRootElements<HTMLImageElement>(['img']);
+
+  useEffect(() => {
+    let dataSourceImages: DataSource | null = null;
+
+    let lightbox = new PhotoSwipeLightbox({
+      pswpModule: PhotoSwipe,
+      wheelToZoom: true,
+      arrowPrevSVG:
+        '<svg class="MuiSvgIcon-root MuiSvgIcon-fontSizeLarge  css-c1sh5i" focusable="false" aria-hidden="true" viewBox="0 0 24 24" data-testid="ArrowBackIosIcon" aria-label="fontSize large"><path d="M11.67 3.87 9.9 2.1 0 12l9.9 9.9 1.77-1.77L3.54 12z"></path></svg>',
+      arrowNextSVG:
+        '<svg class="MuiSvgIcon-root MuiSvgIcon-fontSizeLarge  css-c1sh5i" focusable="false" aria-hidden="true" viewBox="0 0 24 24" data-testid="ArrowForwardIosIcon" aria-label="fontSize large"><path d="M6.23 20.23 8 22l10-10L8 2 6.23 3.77 14.46 12z"></path></svg>',
+      closeSVG:
+        '<svg class="MuiSvgIcon-root MuiSvgIcon-fontSizeLarge  css-c1sh5i" focusable="false" aria-hidden="true" viewBox="0 0 24 24" data-testid="CloseIcon" aria-label="fontSize large"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"></path></svg>',
+      zoomSVG:
+        '<svg class="MuiSvgIcon-root MuiSvgIcon-fontSizeLarge  css-c1sh5i" focusable="false" aria-hidden="true" viewBox="0 0 24 24" data-testid="ZoomInIcon" aria-label="fontSize large"><path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path><path d="M12 10h-2v2H9v-2H7V9h2V7h1v2h2v1z"></path></svg>',
+    });
+
+    images.forEach((image, index) => {
+      image.onclick = () => {
+        if (dataSourceImages === null) {
+          dataSourceImages = images.map(dataSourceImage => {
+            return {
+              element: dataSourceImage,
+              src: dataSourceImage.src,
+              msrc: dataSourceImage.src,
+              alt: dataSourceImage.alt,
+              width: dataSourceImage.clientWidth,
+              height: dataSourceImage.clientHeight,
+            };
+          });
+        }
+        lightbox.loadAndOpen(index, dataSourceImages);
+        return false;
+      };
+    });
+    lightbox.init();
+
+    return () => {
+      lightbox.destroy();
+      lightbox = null;
+    };
+  }, [images]);
+
+  return null;
+};

plugins/techdocs-module-addons-contrib/src/LigthBox/index.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './LightBox';

plugins/techdocs-module-addons-contrib/src/LigthBox/lightbox.css

@@ -0,0 +1,7 @@
+.pswp {
+  --pswp-bg: #f8f8f8;
+}
+.pswp__counter {
+  color: rgba(0, 0, 0, 0.87);
+  text-shadow: none;
+}

plugins/techdocs-module-addons-contrib/src/index.ts

@@ -25,6 +25,7 @@ export {
   ExpandableNavigation,
   ReportIssue,
   TextSize,
+  LightBox,
 } from './plugin';
 export type {
   ReportIssueProps,

plugins/techdocs-module-addons-contrib/src/plugin.ts

@@ -22,6 +22,7 @@ import {
 import { ExpandableNavigationAddon } from './ExpandableNavigation';
 import { ReportIssueAddon, ReportIssueProps } from './ReportIssue';
 import { TextSizeAddon } from './TextSize';
+import { LightBoxAddon } from './LigthBox';
 
 /**
  * The TechDocs addons contrib plugin
@@ -203,3 +204,49 @@ export const TextSize = techdocsModuleAddonsContribPlugin.provide(
     component: TextSizeAddon,
   }),
 );
+
+/**
+ * This TechDocs addon allows users to open images in a lightbox on documentation pages, they can navigate between images if there are several on one page.
+ *
+ * @remarks
+ * The image size of the lightbox image is the same as the image size on the document page.
+ *
+ * @example
+ * Here's a simple example:
+ * ```
+ * import {
+ *   DefaultTechDocsHome,
+ *   TechDocsIndexPage,
+ *   TechDocsReaderPage,
+ * } from '@backstage/plugin-techdocs';
+ * import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
+ * import { LightBox } from '@backstage/plugin-techdocs-module-addons-contrib';
+ *
+ *
+ * const AppRoutes = () => {
+ *   <FlatRoutes>
+ *     // other plugin routes
+ *     <Route path="/docs" element={<TechDocsIndexPage />}>
+ *       <DefaultTechDocsHome />
+ *     </Route>
+ *     <Route
+ *       path="/docs/:namespace/:kind/:name/*"
+ *       element={<TechDocsReaderPage />}
+ *     >
+ *       <TechDocsAddons>
+ *         <LightBox />
+ *       </TechDocsAddons>
+ *     </Route>
+ *   </FlatRoutes>;
+ * };
+ * ```
+ *
+ * @public
+ */
+export const LightBox = techdocsModuleAddonsContribPlugin.provide(
+  createTechDocsAddonExtension({
+    name: 'LightBox',
+    location: TechDocsAddonLocations.Content,
+    component: LightBoxAddon,
+  }),
+);

plugins/techdocs/src/reader/components/TechDocsReaderPage/TechDocsReaderPage.tsx

@@ -102,6 +102,7 @@ CONFIGURATION 4: <TechDocsReaderPage> and provided content in <Route>
     <ExpandableNavigation />
     <ReportIssue />
     <TextSize />
+    <LightBox />
   </TechDocsAddons>
 </Route>
 

yarn.lock

@@ -8225,6 +8225,7 @@ __metadata:
     cross-fetch: ^3.1.5
     git-url-parse: ^13.0.0
     msw: ^0.49.0
+    photoswipe: ^5.3.5
     react-use: ^17.2.4
   peerDependencies:
     react: ^16.13.1 || ^17.0.0
@@ -31430,6 +31431,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"photoswipe@npm:^5.3.5":
+  version: 5.3.5
+  resolution: "photoswipe@npm:5.3.5"
+  checksum: bd3eafebffc114210b8e5403746b48a9bfe436cca05a65f8d5efd6eacea785a51f0f124d7326c8f651d754d76124c9768a920383843c4a619da582a86e535b27
+  languageName: node
+  linkType: hard
+
 "picocolors@npm:^1.0.0":
   version: 1.0.0
   resolution: "picocolors@npm:1.0.0"