@backstage/plugin-techdocs-react 0.1.1-next.2 → 1.0.1-next.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @backstage/plugin-techdocs-react
 
+## 1.0.1-next.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/core-components@0.9.5-next.1
+  - @backstage/core-plugin-api@1.0.3-next.0
+  - @backstage/catalog-model@1.0.3-next.0
+
+## 1.0.1-next.0
+
+### Patch Changes
+
+- 3b45ad701f: Creates a `TechDocsShadowDom` component that takes a tree of elements and an `onAppend` handler:
+
+  - Calls the `onAppend` handler when appending the element tree to the shadow root;
+  - Also dispatches an event when styles are loaded to let transformers know that the computed styles are ready to be consumed.
+
+- Updated dependencies
+  - @backstage/core-components@0.9.5-next.0
+
+## 1.0.0
+
+### Major Changes
+
+- 0ad901569f: The TechDocs Addon framework is now generally available.
+
+### Patch Changes
+
+- 52419be116: Create a new addon location called "Settings", it is designed for addons that allow users to customize the reading experience in documentation pages.
+
+  Usage example:
+
+  ```tsx
+  const TextSize = techdocsModuleAddonsContribPlugin.provide(
+    createTechDocsAddonExtension({
+      name: 'TextSize',
+      location: TechDocsAddonLocations.Settings,
+      component: TextSizeAddon,
+    }),
+  );
+  ```
+
+- c25e880e36: Added overload signatures for `createTechDocsAddonExtension` to handle TechDocs addons without props.
+- 52fddad92d: The `TechDocsStorageApi` and its associated ref are now exported by `@backstage/plugin-techdocs-react`. The API interface, ref, and types are now deprecated in `@backstage/plugin-techdocs` and will be removed in a future release.
+- 075a9a067b: Updated the return type of `createTechDocsAddonExtension` to better reflect the fact that passing children to Addon components is not a valid use-case.
+- Updated dependencies
+  - @backstage/core-components@0.9.4
+  - @backstage/core-plugin-api@1.0.2
+  - @backstage/catalog-model@1.0.2
+
 ## 0.1.1-next.2
 
 ### Patch Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-techdocs-react",
-  "version": "0.1.1-next.2",
+  "version": "1.0.1-next.1",
   "main": "../dist/index.esm.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.alpha.d.ts

@@ -11,20 +11,28 @@ import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Dispatch } from 'react';
 import { Entity } from '@backstage/catalog-model';
 import { Extension } from '@backstage/core-plugin-api';
+import { PropsWithChildren } from 'react';
 import { default as React_2 } from 'react';
 import { ReactNode } from 'react';
 import { SetStateAction } from 'react';
 
 /**
- * Create a TechDocs addon.
- * @alpha
+ * Create a TechDocs addon overload signature without props.
+ * @public
+ */
+export declare function createTechDocsAddonExtension(options: TechDocsAddonOptions): Extension<() => JSX.Element | null>;
+
+/**
+ * Create a TechDocs addon overload signature with props.
+ * @public
  */
 export declare function createTechDocsAddonExtension<TComponentProps>(options: TechDocsAddonOptions<TComponentProps>): Extension<(props: TComponentProps) => JSX.Element | null>;
 
 /**
- * @alpha
+ * Name for the event dispatched when ShadowRoot styles are loaded.
+ * @public
  */
-export declare const defaultTechDocsReaderPageValue: TechDocsReaderPageValue;
+export declare const SHADOW_DOM_STYLE_LOAD_EVENT = "TECH_DOCS_SHADOW_DOM_STYLE_LOAD";
 
 /**
  * The outcome of a docs sync operation.
@@ -35,13 +43,13 @@ export declare type SyncResult = 'cached' | 'updated';
 
 /**
  * Marks the <TechDocsAddons> registry component.
- * @alpha
+ * @public
  */
 export declare const TECHDOCS_ADDONS_WRAPPER_KEY = "techdocs.addons.wrapper.v1";
 
 /**
  * Locations for which TechDocs addons may be declared and rendered.
- * @alpha
+ * @public
  */
 export declare const TechDocsAddonLocations: Readonly<{
     /**
@@ -76,7 +84,7 @@ export declare const TechDocsAddonLocations: Readonly<{
 
 /**
  * Options for creating a TechDocs addon.
- * @alpha
+ * @public
  */
 export declare type TechDocsAddonOptions<TAddonProps = {}> = {
     name: string;
@@ -86,7 +94,7 @@ export declare type TechDocsAddonOptions<TAddonProps = {}> = {
 
 /**
  * TechDocs Addon registry.
- * @alpha
+ * @public
  */
 export declare const TechDocsAddons: React_2.ComponentType;
 
@@ -172,6 +180,72 @@ export declare type TechDocsReaderPageValue = {
     onReady?: () => void;
 };
 
+/**
+ * Renders a tree of elements in a Shadow DOM.
+ *
+ * @remarks
+ * Centers the styles loaded event to avoid having multiple locations setting the opacity style in Shadow DOM causing the screen to flash multiple times,
+ * so if you want to know when Shadow DOM styles are computed, you can listen for the "TECH_DOCS_SHADOW_DOM_STYLE_LOAD" event dispatched by the element tree.
+ *
+ * @example
+ * Here is an example using this component and also listening for styles loaded event:
+ *```jsx
+ * import {
+ *   TechDocsShadowDom,
+ *   SHADOW_DOM_STYLE_LOAD_EVENT,
+ * } from '@backstage/plugin-techdocs-react';
+ *
+ * export const TechDocsReaderPageContent = ({ entity }: TechDocsReaderPageContentProps) => {
+ *   // ...
+ *   const dom = useTechDocsReaderDom(entity);
+ *
+ *   useEffect(() => {
+ *     const updateSidebarPosition = () => {
+ *       // ...
+ *     };
+ *     dom?.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);
+ *     return () => {
+ *       dom?.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);
+ *     };
+ *   }, [dom]);
+ *
+ *   const handleDomAppend = useCallback(
+ *     (newShadowRoot: ShadowRoot) => {
+ *       setShadowRoot(newShadowRoot);
+ *     },
+ *     [setShadowRoot],
+ *   );
+ *
+ *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;
+ * };
+ * ```
+ *
+ * @param props - see {@link TechDocsShadowDomProps}.
+ * @public
+ */
+export declare const TechDocsShadowDom: ({ element, onAppend, children, }: TechDocsShadowDomProps) => JSX.Element;
+
+/**
+ * Props for {@link TechDocsShadowDom}.
+ *
+ * @remarks
+ * If you want to use portals to render Material UI components in the Shadow DOM,
+ * you must render these portals as children because this component wraps its children in a Material UI StylesProvider
+ * to ensure that Material UI styles are applied.
+ *
+ * @public
+ */
+export declare type TechDocsShadowDomProps = PropsWithChildren<{
+    /**
+     * Element tree that is appended to ShadowRoot.
+     */
+    element: Element;
+    /**
+     * Callback called when the element tree is appended in ShadowRoot.
+     */
+    onAppend?: (shadowRoot: ShadowRoot) => void;
+}>;
+
 /**
  * API which talks to TechDocs storage to fetch files to render.
  *
@@ -193,10 +267,53 @@ export declare interface TechDocsStorageApi {
  */
 export declare const techdocsStorageApiRef: ApiRef<TechDocsStorageApi>;
 
+/**
+ * Returns the style's loading state.
+ *
+ * @example
+ * Here's an example that updates the sidebar position only after styles are calculated:
+ * ```jsx
+ * import {
+ *   TechDocsShadowDom,
+ *   useShadowDomStylesLoading,
+ * } from '@backstage/plugin-techdocs-react';
+ *
+ * export const TechDocsReaderPageContent = () => {
+ *   // ...
+ *   const dom = useTechDocsReaderDom(entity);
+ *   const isStyleLoading = useShadowDomStylesLoading(dom);
+ *
+ *   const updateSidebarPosition = useCallback(() => {
+ *     //...
+ *   }, [dom]);
+ *
+ *   useEffect(() => {
+ *     if (!isStyleLoading) {
+ *       updateSidebarPosition();
+ *     }
+ *   }, [isStyleLoading, updateSidebarPosition]);
+ *
+ *   const handleDomAppend = useCallback(
+ *     (newShadowRoot: ShadowRoot) => {
+ *       setShadowRoot(newShadowRoot);
+ *     },
+ *     [setShadowRoot],
+ *   );
+ *
+ *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;
+ * };
+ * ```
+ *
+ * @param element - which is the ShadowRoot tree.
+ * @returns a boolean value, true if styles are being loaded.
+ * @public
+ */
+export declare const useShadowDomStylesLoading: (element: Element | null) => boolean;
+
 /**
  * Hook for use within TechDocs addons that provides access to the underlying
  * shadow root of the current page, allowing the DOM within to be mutated.
- * @alpha
+ * @public
  */
 export declare const useShadowRoot: () => ShadowRoot | undefined;
 
@@ -204,19 +321,19 @@ export declare const useShadowRoot: () => ShadowRoot | undefined;
  * Convenience hook for use within TechDocs addons that provides access to
  * elements that match a given selector within the shadow root.
  *
- * @alpha
+ * @public
  */
 export declare const useShadowRootElements: <TReturnedElement extends HTMLElement = HTMLElement>(selectors: string[]) => TReturnedElement[];
 
 /**
  * Hook for retreiving a selection within the ShadowRoot.
- * @alpha
+ * @public
  */
 export declare const useShadowRootSelection: (wait?: number) => Selection | null;
 
 /**
  * hook to use addons in components
- * @alpha
+ * @public
  */
 export declare const useTechDocsAddons: () => {
     renderComponentByName: (name: string) => JSX.Element | null;
@@ -225,7 +342,7 @@ export declare const useTechDocsAddons: () => {
 
 /**
  * Hook used to get access to shared state between reader page components.
- * @alpha
+ * @public
  */
 export declare const useTechDocsReaderPage: () => TechDocsReaderPageValue;
 

package/dist/index.beta.d.ts

@@ -11,13 +11,28 @@ import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Dispatch } from 'react';
 import { Entity } from '@backstage/catalog-model';
 import { Extension } from '@backstage/core-plugin-api';
+import { PropsWithChildren } from 'react';
 import { default as React_2 } from 'react';
 import { ReactNode } from 'react';
 import { SetStateAction } from 'react';
 
-/* Excluded from this release type: createTechDocsAddonExtension */
+/**
+ * Create a TechDocs addon overload signature without props.
+ * @public
+ */
+export declare function createTechDocsAddonExtension(options: TechDocsAddonOptions): Extension<() => JSX.Element | null>;
 
-/* Excluded from this release type: defaultTechDocsReaderPageValue */
+/**
+ * Create a TechDocs addon overload signature with props.
+ * @public
+ */
+export declare function createTechDocsAddonExtension<TComponentProps>(options: TechDocsAddonOptions<TComponentProps>): Extension<(props: TComponentProps) => JSX.Element | null>;
+
+/**
+ * Name for the event dispatched when ShadowRoot styles are loaded.
+ * @public
+ */
+export declare const SHADOW_DOM_STYLE_LOAD_EVENT = "TECH_DOCS_SHADOW_DOM_STYLE_LOAD";
 
 /**
  * The outcome of a docs sync operation.
@@ -26,13 +41,62 @@ import { SetStateAction } from 'react';
  */
 export declare type SyncResult = 'cached' | 'updated';
 
-/* Excluded from this release type: TECHDOCS_ADDONS_WRAPPER_KEY */
+/**
+ * Marks the <TechDocsAddons> registry component.
+ * @public
+ */
+export declare const TECHDOCS_ADDONS_WRAPPER_KEY = "techdocs.addons.wrapper.v1";
 
-/* Excluded from this release type: TechDocsAddonLocations */
+/**
+ * Locations for which TechDocs addons may be declared and rendered.
+ * @public
+ */
+export declare const TechDocsAddonLocations: Readonly<{
+    /**
+     * These addons fill up the header from the right, on the same line as the
+     * title.
+     */
+    readonly Header: "Header";
+    /**
+     * These addons appear below the header and above all content; tooling addons
+     * can be inserted for convenience.
+     */
+    readonly Subheader: "Subheader";
+    /**
+     * These addons are items added to the settings menu list and are designed to make
+     * the reader experience customizable, for example accessibility options
+     */
+    readonly Settings: "Settings";
+    /**
+     * These addons appear left of the content and above the navigation.
+     */
+    readonly PrimarySidebar: "PrimarySidebar";
+    /**
+     * These addons appear right of the content and above the table of contents.
+     */
+    readonly SecondarySidebar: "SecondarySidebar";
+    /**
+     * A virtual location which allows mutation of all content within the shadow
+     * root by transforming DOM nodes. These addons should return null on render.
+     */
+    readonly Content: "Content";
+}>;
 
-/* Excluded from this release type: TechDocsAddonOptions */
+/**
+ * Options for creating a TechDocs addon.
+ * @public
+ */
+export declare type TechDocsAddonOptions<TAddonProps = {}> = {
+    name: string;
+    location: keyof typeof TechDocsAddonLocations;
+    component: ComponentType<TAddonProps>;
+};
 
-/* Excluded from this release type: TechDocsAddons */
+/**
+ * TechDocs Addon registry.
+ * @public
+ */
+export declare const TechDocsAddons: React_2.ComponentType;
 
 /**
  * API to talk to techdocs-backend.
@@ -116,6 +180,72 @@ export declare type TechDocsReaderPageValue = {
     onReady?: () => void;
 };
 
+/**
+ * Renders a tree of elements in a Shadow DOM.
+ *
+ * @remarks
+ * Centers the styles loaded event to avoid having multiple locations setting the opacity style in Shadow DOM causing the screen to flash multiple times,
+ * so if you want to know when Shadow DOM styles are computed, you can listen for the "TECH_DOCS_SHADOW_DOM_STYLE_LOAD" event dispatched by the element tree.
+ *
+ * @example
+ * Here is an example using this component and also listening for styles loaded event:
+ *```jsx
+ * import {
+ *   TechDocsShadowDom,
+ *   SHADOW_DOM_STYLE_LOAD_EVENT,
+ * } from '@backstage/plugin-techdocs-react';
+ *
+ * export const TechDocsReaderPageContent = ({ entity }: TechDocsReaderPageContentProps) => {
+ *   // ...
+ *   const dom = useTechDocsReaderDom(entity);
+ *
+ *   useEffect(() => {
+ *     const updateSidebarPosition = () => {
+ *       // ...
+ *     };
+ *     dom?.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);
+ *     return () => {
+ *       dom?.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);
+ *     };
+ *   }, [dom]);
+ *
+ *   const handleDomAppend = useCallback(
+ *     (newShadowRoot: ShadowRoot) => {
+ *       setShadowRoot(newShadowRoot);
+ *     },
+ *     [setShadowRoot],
+ *   );
+ *
+ *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;
+ * };
+ * ```
+ *
+ * @param props - see {@link TechDocsShadowDomProps}.
+ * @public
+ */
+export declare const TechDocsShadowDom: ({ element, onAppend, children, }: TechDocsShadowDomProps) => JSX.Element;
+
+/**
+ * Props for {@link TechDocsShadowDom}.
+ *
+ * @remarks
+ * If you want to use portals to render Material UI components in the Shadow DOM,
+ * you must render these portals as children because this component wraps its children in a Material UI StylesProvider
+ * to ensure that Material UI styles are applied.
+ *
+ * @public
+ */
+export declare type TechDocsShadowDomProps = PropsWithChildren<{
+    /**
+     * Element tree that is appended to ShadowRoot.
+     */
+    element: Element;
+    /**
+     * Callback called when the element tree is appended in ShadowRoot.
+     */
+    onAppend?: (shadowRoot: ShadowRoot) => void;
+}>;
+
 /**
  * API which talks to TechDocs storage to fetch files to render.
  *
@@ -137,14 +267,83 @@ export declare interface TechDocsStorageApi {
  */
 export declare const techdocsStorageApiRef: ApiRef<TechDocsStorageApi>;
 
-/* Excluded from this release type: useShadowRoot */
+/**
+ * Returns the style's loading state.
+ *
+ * @example
+ * Here's an example that updates the sidebar position only after styles are calculated:
+ * ```jsx
+ * import {
+ *   TechDocsShadowDom,
+ *   useShadowDomStylesLoading,
+ * } from '@backstage/plugin-techdocs-react';
+ *
+ * export const TechDocsReaderPageContent = () => {
+ *   // ...
+ *   const dom = useTechDocsReaderDom(entity);
+ *   const isStyleLoading = useShadowDomStylesLoading(dom);
+ *
+ *   const updateSidebarPosition = useCallback(() => {
+ *     //...
+ *   }, [dom]);
+ *
+ *   useEffect(() => {
+ *     if (!isStyleLoading) {
+ *       updateSidebarPosition();
+ *     }
+ *   }, [isStyleLoading, updateSidebarPosition]);
+ *
+ *   const handleDomAppend = useCallback(
+ *     (newShadowRoot: ShadowRoot) => {
+ *       setShadowRoot(newShadowRoot);
+ *     },
+ *     [setShadowRoot],
+ *   );
+ *
+ *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;
+ * };
+ * ```
+ *
+ * @param element - which is the ShadowRoot tree.
+ * @returns a boolean value, true if styles are being loaded.
+ * @public
+ */
+export declare const useShadowDomStylesLoading: (element: Element | null) => boolean;
+
+/**
+ * Hook for use within TechDocs addons that provides access to the underlying
+ * shadow root of the current page, allowing the DOM within to be mutated.
+ * @public
+ */
+export declare const useShadowRoot: () => ShadowRoot | undefined;
 
-/* Excluded from this release type: useShadowRootElements */
+/**
+ * Convenience hook for use within TechDocs addons that provides access to
+ * elements that match a given selector within the shadow root.
+ *
+ * @public
+ */
+export declare const useShadowRootElements: <TReturnedElement extends HTMLElement = HTMLElement>(selectors: string[]) => TReturnedElement[];
 
-/* Excluded from this release type: useShadowRootSelection */
+/**
+ * Hook for retreiving a selection within the ShadowRoot.
+ * @public
+ */
+export declare const useShadowRootSelection: (wait?: number) => Selection | null;
 
-/* Excluded from this release type: useTechDocsAddons */
+/**
+ * hook to use addons in components
+ * @public
+ */
+export declare const useTechDocsAddons: () => {
+    renderComponentByName: (name: string) => JSX.Element | null;
+    renderComponentsByLocation: (location: keyof typeof TechDocsAddonLocations) => (JSX.Element | null)[] | null;
+};
 
-/* Excluded from this release type: useTechDocsReaderPage */
+/**
+ * Hook used to get access to shared state between reader page components.
+ * @public
+ */
+export declare const useTechDocsReaderPage: () => TechDocsReaderPageValue;
 
 export { }

package/dist/index.d.ts

@@ -11,13 +11,28 @@ import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Dispatch } from 'react';
 import { Entity } from '@backstage/catalog-model';
 import { Extension } from '@backstage/core-plugin-api';
+import { PropsWithChildren } from 'react';
 import { default as React_2 } from 'react';
 import { ReactNode } from 'react';
 import { SetStateAction } from 'react';
 
-/* Excluded from this release type: createTechDocsAddonExtension */
+/**
+ * Create a TechDocs addon overload signature without props.
+ * @public
+ */
+export declare function createTechDocsAddonExtension(options: TechDocsAddonOptions): Extension<() => JSX.Element | null>;
 
-/* Excluded from this release type: defaultTechDocsReaderPageValue */
+/**
+ * Create a TechDocs addon overload signature with props.
+ * @public
+ */
+export declare function createTechDocsAddonExtension<TComponentProps>(options: TechDocsAddonOptions<TComponentProps>): Extension<(props: TComponentProps) => JSX.Element | null>;
+
+/**
+ * Name for the event dispatched when ShadowRoot styles are loaded.
+ * @public
+ */
+export declare const SHADOW_DOM_STYLE_LOAD_EVENT = "TECH_DOCS_SHADOW_DOM_STYLE_LOAD";
 
 /**
  * The outcome of a docs sync operation.
@@ -26,13 +41,62 @@ import { SetStateAction } from 'react';
  */
 export declare type SyncResult = 'cached' | 'updated';
 
-/* Excluded from this release type: TECHDOCS_ADDONS_WRAPPER_KEY */
+/**
+ * Marks the <TechDocsAddons> registry component.
+ * @public
+ */
+export declare const TECHDOCS_ADDONS_WRAPPER_KEY = "techdocs.addons.wrapper.v1";
 
-/* Excluded from this release type: TechDocsAddonLocations */
+/**
+ * Locations for which TechDocs addons may be declared and rendered.
+ * @public
+ */
+export declare const TechDocsAddonLocations: Readonly<{
+    /**
+     * These addons fill up the header from the right, on the same line as the
+     * title.
+     */
+    readonly Header: "Header";
+    /**
+     * These addons appear below the header and above all content; tooling addons
+     * can be inserted for convenience.
+     */
+    readonly Subheader: "Subheader";
+    /**
+     * These addons are items added to the settings menu list and are designed to make
+     * the reader experience customizable, for example accessibility options
+     */
+    readonly Settings: "Settings";
+    /**
+     * These addons appear left of the content and above the navigation.
+     */
+    readonly PrimarySidebar: "PrimarySidebar";
+    /**
+     * These addons appear right of the content and above the table of contents.
+     */
+    readonly SecondarySidebar: "SecondarySidebar";
+    /**
+     * A virtual location which allows mutation of all content within the shadow
+     * root by transforming DOM nodes. These addons should return null on render.
+     */
+    readonly Content: "Content";
+}>;
 
-/* Excluded from this release type: TechDocsAddonOptions */
+/**
+ * Options for creating a TechDocs addon.
+ * @public
+ */
+export declare type TechDocsAddonOptions<TAddonProps = {}> = {
+    name: string;
+    location: keyof typeof TechDocsAddonLocations;
+    component: ComponentType<TAddonProps>;
+};
 
-/* Excluded from this release type: TechDocsAddons */
+/**
+ * TechDocs Addon registry.
+ * @public
+ */
+export declare const TechDocsAddons: React_2.ComponentType;
 
 /**
  * API to talk to techdocs-backend.
@@ -116,6 +180,72 @@ export declare type TechDocsReaderPageValue = {
     onReady?: () => void;
 };
 
+/**
+ * Renders a tree of elements in a Shadow DOM.
+ *
+ * @remarks
+ * Centers the styles loaded event to avoid having multiple locations setting the opacity style in Shadow DOM causing the screen to flash multiple times,
+ * so if you want to know when Shadow DOM styles are computed, you can listen for the "TECH_DOCS_SHADOW_DOM_STYLE_LOAD" event dispatched by the element tree.
+ *
+ * @example
+ * Here is an example using this component and also listening for styles loaded event:
+ *```jsx
+ * import {
+ *   TechDocsShadowDom,
+ *   SHADOW_DOM_STYLE_LOAD_EVENT,
+ * } from '@backstage/plugin-techdocs-react';
+ *
+ * export const TechDocsReaderPageContent = ({ entity }: TechDocsReaderPageContentProps) => {
+ *   // ...
+ *   const dom = useTechDocsReaderDom(entity);
+ *
+ *   useEffect(() => {
+ *     const updateSidebarPosition = () => {
+ *       // ...
+ *     };
+ *     dom?.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);
+ *     return () => {
+ *       dom?.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);
+ *     };
+ *   }, [dom]);
+ *
+ *   const handleDomAppend = useCallback(
+ *     (newShadowRoot: ShadowRoot) => {
+ *       setShadowRoot(newShadowRoot);
+ *     },
+ *     [setShadowRoot],
+ *   );
+ *
+ *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;
+ * };
+ * ```
+ *
+ * @param props - see {@link TechDocsShadowDomProps}.
+ * @public
+ */
+export declare const TechDocsShadowDom: ({ element, onAppend, children, }: TechDocsShadowDomProps) => JSX.Element;
+
+/**
+ * Props for {@link TechDocsShadowDom}.
+ *
+ * @remarks
+ * If you want to use portals to render Material UI components in the Shadow DOM,
+ * you must render these portals as children because this component wraps its children in a Material UI StylesProvider
+ * to ensure that Material UI styles are applied.
+ *
+ * @public
+ */
+export declare type TechDocsShadowDomProps = PropsWithChildren<{
+    /**
+     * Element tree that is appended to ShadowRoot.
+     */
+    element: Element;
+    /**
+     * Callback called when the element tree is appended in ShadowRoot.
+     */
+    onAppend?: (shadowRoot: ShadowRoot) => void;
+}>;
+
 /**
  * API which talks to TechDocs storage to fetch files to render.
  *
@@ -137,14 +267,83 @@ export declare interface TechDocsStorageApi {
  */
 export declare const techdocsStorageApiRef: ApiRef<TechDocsStorageApi>;
 
-/* Excluded from this release type: useShadowRoot */
+/**
+ * Returns the style's loading state.
+ *
+ * @example
+ * Here's an example that updates the sidebar position only after styles are calculated:
+ * ```jsx
+ * import {
+ *   TechDocsShadowDom,
+ *   useShadowDomStylesLoading,
+ * } from '@backstage/plugin-techdocs-react';
+ *
+ * export const TechDocsReaderPageContent = () => {
+ *   // ...
+ *   const dom = useTechDocsReaderDom(entity);
+ *   const isStyleLoading = useShadowDomStylesLoading(dom);
+ *
+ *   const updateSidebarPosition = useCallback(() => {
+ *     //...
+ *   }, [dom]);
+ *
+ *   useEffect(() => {
+ *     if (!isStyleLoading) {
+ *       updateSidebarPosition();
+ *     }
+ *   }, [isStyleLoading, updateSidebarPosition]);
+ *
+ *   const handleDomAppend = useCallback(
+ *     (newShadowRoot: ShadowRoot) => {
+ *       setShadowRoot(newShadowRoot);
+ *     },
+ *     [setShadowRoot],
+ *   );
+ *
+ *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;
+ * };
+ * ```
+ *
+ * @param element - which is the ShadowRoot tree.
+ * @returns a boolean value, true if styles are being loaded.
+ * @public
+ */
+export declare const useShadowDomStylesLoading: (element: Element | null) => boolean;
+
+/**
+ * Hook for use within TechDocs addons that provides access to the underlying
+ * shadow root of the current page, allowing the DOM within to be mutated.
+ * @public
+ */
+export declare const useShadowRoot: () => ShadowRoot | undefined;
 
-/* Excluded from this release type: useShadowRootElements */
+/**
+ * Convenience hook for use within TechDocs addons that provides access to
+ * elements that match a given selector within the shadow root.
+ *
+ * @public
+ */
+export declare const useShadowRootElements: <TReturnedElement extends HTMLElement = HTMLElement>(selectors: string[]) => TReturnedElement[];
 
-/* Excluded from this release type: useShadowRootSelection */
+/**
+ * Hook for retreiving a selection within the ShadowRoot.
+ * @public
+ */
+export declare const useShadowRootSelection: (wait?: number) => Selection | null;
 
-/* Excluded from this release type: useTechDocsAddons */
+/**
+ * hook to use addons in components
+ * @public
+ */
+export declare const useTechDocsAddons: () => {
+    renderComponentByName: (name: string) => JSX.Element | null;
+    renderComponentsByLocation: (location: keyof typeof TechDocsAddonLocations) => (JSX.Element | null)[] | null;
+};
 
-/* Excluded from this release type: useTechDocsReaderPage */
+/**
+ * Hook used to get access to shared state between reader page components.
+ * @public
+ */
+export declare const useTechDocsReaderPage: () => TechDocsReaderPageValue;
 
 export { }

package/dist/index.esm.js

@@ -1,9 +1,12 @@
-import React, { useCallback, memo, useState, useContext, useMemo, useEffect } from 'react';
+import React, { useCallback, memo, useState, useContext, useEffect, useMemo } from 'react';
 import { useOutlet } from 'react-router-dom';
 import { attachComponentData, createReactExtension, useElementFilter, createApiRef, useApi } from '@backstage/core-plugin-api';
 import useAsync from 'react-use/lib/useAsync';
 import { stringifyEntityRef } from '@backstage/catalog-model';
 import { createVersionedContext, createVersionedValueMap } from '@backstage/version-bridge';
+import { create } from 'jss';
+import { jssPreset, StylesProvider } from '@material-ui/styles';
+import { Progress } from '@backstage/core-components';
 import debounce from 'lodash/debounce';
 
 const TECHDOCS_ADDONS_KEY = "techdocs.addons.addon.v1";
@@ -132,6 +135,102 @@ const useTechDocsReaderPage = () => {
   return context;
 };
 
+const TechDocsAddonLocations = Object.freeze({
+  Header: "Header",
+  Subheader: "Subheader",
+  Settings: "Settings",
+  PrimarySidebar: "PrimarySidebar",
+  SecondarySidebar: "SecondarySidebar",
+  Content: "Content"
+});
+
+const SHADOW_DOM_STYLE_LOAD_EVENT = "TECH_DOCS_SHADOW_DOM_STYLE_LOAD";
+const useShadowDomStylesEvents = (element) => {
+  useEffect(() => {
+    var _a;
+    if (!element) {
+      return () => {
+      };
+    }
+    const styles = element.querySelectorAll('head > link[rel="stylesheet"]');
+    let count = (_a = styles == null ? void 0 : styles.length) != null ? _a : 0;
+    const event = new CustomEvent(SHADOW_DOM_STYLE_LOAD_EVENT);
+    if (!count) {
+      element.dispatchEvent(event);
+      return () => {
+      };
+    }
+    const handleLoad = () => {
+      if (--count === 0) {
+        element.dispatchEvent(event);
+      }
+    };
+    styles == null ? void 0 : styles.forEach((style) => {
+      style.addEventListener("load", handleLoad);
+    });
+    return () => {
+      styles == null ? void 0 : styles.forEach((style) => {
+        style.removeEventListener("load", handleLoad);
+      });
+    };
+  }, [element]);
+};
+const useShadowDomStylesLoading = (element) => {
+  const [loading, setLoading] = useState(false);
+  useEffect(() => {
+    if (!element)
+      return () => {
+      };
+    setLoading(true);
+    const style = element.style;
+    style.setProperty("opacity", "0");
+    const handleLoad = () => {
+      setLoading(false);
+      style.setProperty("opacity", "1");
+    };
+    element.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, handleLoad);
+    return () => {
+      element.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, handleLoad);
+    };
+  }, [element]);
+  return loading;
+};
+const TechDocsShadowDom = ({
+  element,
+  onAppend,
+  children
+}) => {
+  const [jss, setJss] = useState(create({
+    ...jssPreset(),
+    insertionPoint: void 0
+  }));
+  useShadowDomStylesEvents(element);
+  const loading = useShadowDomStylesLoading(element);
+  const ref = useCallback((shadowHost) => {
+    if (!element || !shadowHost)
+      return;
+    setJss(create({
+      ...jssPreset(),
+      insertionPoint: element.querySelector("head") || void 0
+    }));
+    let shadowRoot = shadowHost.shadowRoot;
+    if (!shadowRoot) {
+      shadowRoot = shadowHost.attachShadow({ mode: "open" });
+    }
+    shadowRoot.replaceChildren(element);
+    if (typeof onAppend === "function") {
+      onAppend(shadowRoot);
+    }
+  }, [element, onAppend]);
+  return /* @__PURE__ */ React.createElement(React.Fragment, null, loading && /* @__PURE__ */ React.createElement(Progress, null), /* @__PURE__ */ React.createElement(StylesProvider, {
+    jss,
+    sheetsManager: /* @__PURE__ */ new Map()
+  }, /* @__PURE__ */ React.createElement("div", {
+    ref,
+    "data-testid": "techdocs-native-shadowroot"
+  }), children));
+};
+
 const useShadowRoot = () => {
   const { shadowRoot } = useTechDocsReaderPage();
   return shadowRoot;
@@ -164,14 +263,5 @@ const useShadowRootSelection = (wait = 0) => {
   return selection;
 };
 
-const TechDocsAddonLocations = Object.freeze({
-  Header: "Header",
-  Subheader: "Subheader",
-  Settings: "Settings",
-  PrimarySidebar: "PrimarySidebar",
-  SecondarySidebar: "SecondarySidebar",
-  Content: "Content"
-});
-
-export { TECHDOCS_ADDONS_WRAPPER_KEY, TechDocsAddonLocations, TechDocsAddons, TechDocsReaderPageProvider, createTechDocsAddonExtension, defaultTechDocsReaderPageValue, techdocsApiRef, techdocsStorageApiRef, useShadowRoot, useShadowRootElements, useShadowRootSelection, useTechDocsAddons, useTechDocsReaderPage };
+export { SHADOW_DOM_STYLE_LOAD_EVENT, TECHDOCS_ADDONS_WRAPPER_KEY, TechDocsAddonLocations, TechDocsAddons, TechDocsReaderPageProvider, TechDocsShadowDom, createTechDocsAddonExtension, techdocsApiRef, techdocsStorageApiRef, useShadowDomStylesLoading, useShadowRoot, useShadowRootElements, useShadowRootSelection, useTechDocsAddons, useTechDocsReaderPage };
 //# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.js","sources":["../src/addons.tsx","../src/api.ts","../src/context.tsx","../src/hooks.ts","../src/types.ts"],"sourcesContent":["/*\n * Copyright 2022 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, { useCallback } from 'react';\nimport { useOutlet } from 'react-router-dom';\n\nimport {\n  attachComponentData,\n  createReactExtension,\n  ElementCollection,\n  Extension,\n  useElementFilter,\n} from '@backstage/core-plugin-api';\n\nimport { TechDocsAddonLocations, TechDocsAddonOptions } from './types';\n\nexport const TECHDOCS_ADDONS_KEY = 'techdocs.addons.addon.v1';\n\n/**\n * Marks the <TechDocsAddons> registry component.\n * @alpha\n */\nexport const TECHDOCS_ADDONS_WRAPPER_KEY = 'techdocs.addons.wrapper.v1';\n\n/**\n * TechDocs Addon registry.\n * @alpha\n */\nexport const TechDocsAddons: React.ComponentType = () => null;\n\nattachComponentData(TechDocsAddons, TECHDOCS_ADDONS_WRAPPER_KEY, true);\n\nconst getDataKeyByName = (name: string) => {\n  return `${TECHDOCS_ADDONS_KEY}.${name.toLocaleLowerCase('en-US')}`;\n};\n\n/**\n * Create a TechDocs addon.\n * @alpha\n */\nexport function createTechDocsAddonExtension<TComponentProps>(\n  options: TechDocsAddonOptions<TComponentProps>,\n): Extension<(props: TComponentProps) => JSX.Element | null> {\n  const { name, component: TechDocsAddon } = options;\n  return createReactExtension({\n    name,\n    component: {\n      sync: (props: TComponentProps) => <TechDocsAddon {...props} />,\n    },\n    data: {\n      [TECHDOCS_ADDONS_KEY]: options,\n      [getDataKeyByName(name)]: true,\n    },\n  });\n}\n\nconst getTechDocsAddonByName = (\n  collection: ElementCollection,\n  key: string,\n): JSX.Element | undefined => {\n  return collection.selectByComponentData({ key }).getElements()[0];\n};\n\nconst getAllTechDocsAddons = (collection: ElementCollection) => {\n  return collection\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_WRAPPER_KEY,\n    })\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_KEY,\n    });\n};\n\nconst getAllTechDocsAddonsData = (collection: ElementCollection) => {\n  return collection\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_WRAPPER_KEY,\n    })\n    .findComponentData<TechDocsAddonOptions>({\n      key: TECHDOCS_ADDONS_KEY,\n    });\n};\n\n/**\n * hook to use addons in components\n * @alpha\n */\nexport const useTechDocsAddons = () => {\n  const node = useOutlet();\n  const collection = useElementFilter(node, getAllTechDocsAddons);\n  const options = useElementFilter(node, getAllTechDocsAddonsData);\n\n  const findAddonByData = useCallback(\n    (data: TechDocsAddonOptions | undefined) => {\n      if (!collection || !data) return null;\n      const nameKey = getDataKeyByName(data.name);\n      return getTechDocsAddonByName(collection, nameKey) ?? null;\n    },\n    [collection],\n  );\n\n  const renderComponentByName = useCallback(\n    (name: string) => {\n      const data = options.find(option => option.name === name);\n      return data ? findAddonByData(data) : null;\n    },\n    [options, findAddonByData],\n  );\n\n  const renderComponentsByLocation = useCallback(\n    (location: keyof typeof TechDocsAddonLocations) => {\n      const data = options.filter(option => option.location === location);\n      return data.length ? data.map(findAddonByData) : null;\n    },\n    [options, findAddonByData],\n  );\n\n  return { renderComponentByName, renderComponentsByLocation };\n};\n","/*\n * Copyright 2022 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 { CompoundEntityRef } from '@backstage/catalog-model';\nimport { createApiRef } from '@backstage/core-plugin-api';\nimport { TechDocsEntityMetadata, TechDocsMetadata } from './types';\n\n/**\n * API to talk to techdocs-backend.\n *\n * @public\n */\nexport interface TechDocsApi {\n  getApiOrigin(): Promise<string>;\n  getTechDocsMetadata(entityId: CompoundEntityRef): Promise<TechDocsMetadata>;\n  getEntityMetadata(\n    entityId: CompoundEntityRef,\n  ): Promise<TechDocsEntityMetadata>;\n}\n\n/**\n * Utility API reference for the {@link TechDocsApi}.\n *\n * @public\n */\nexport const techdocsApiRef = createApiRef<TechDocsApi>({\n  id: 'plugin.techdocs.service',\n});\n\n/**\n * The outcome of a docs sync operation.\n *\n * @public\n */\nexport type SyncResult = 'cached' | 'updated';\n\n/**\n * API which talks to TechDocs storage to fetch files to render.\n *\n * @public\n */\nexport interface TechDocsStorageApi {\n  getApiOrigin(): Promise<string>;\n  getStorageUrl(): Promise<string>;\n  getBuilder(): Promise<string>;\n  getEntityDocs(entityId: CompoundEntityRef, path: string): Promise<string>;\n  syncEntityDocs(\n    entityId: CompoundEntityRef,\n    logHandler?: (line: string) => void,\n  ): Promise<SyncResult>;\n  getBaseUrl(\n    oldBaseUrl: string,\n    entityId: CompoundEntityRef,\n    path: string,\n  ): Promise<string>;\n}\n\n/**\n * Utility API reference for the {@link TechDocsStorageApi}.\n *\n * @public\n */\nexport const techdocsStorageApiRef = createApiRef<TechDocsStorageApi>({\n  id: 'plugin.techdocs.storageservice',\n});\n","/*\n * Copyright 2022 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, {\n  Dispatch,\n  SetStateAction,\n  useContext,\n  useState,\n  memo,\n  ReactNode,\n} from 'react';\nimport useAsync, { AsyncState } from 'react-use/lib/useAsync';\n\nimport {\n  CompoundEntityRef,\n  stringifyEntityRef,\n} from '@backstage/catalog-model';\nimport {\n  createVersionedContext,\n  createVersionedValueMap,\n} from '@backstage/version-bridge';\n\nimport { useApi } from '@backstage/core-plugin-api';\n\nimport { techdocsApiRef } from './api';\nimport { TechDocsEntityMetadata, TechDocsMetadata } from './types';\n\nconst areEntityRefsEqual = (\n  prevEntityRef: CompoundEntityRef,\n  nextEntityRef: CompoundEntityRef,\n) => {\n  return (\n    stringifyEntityRef(prevEntityRef) === stringifyEntityRef(nextEntityRef)\n  );\n};\n\n/**\n * @public type for the value of the TechDocsReaderPageContext\n */\nexport type TechDocsReaderPageValue = {\n  metadata: AsyncState<TechDocsMetadata>;\n  entityRef: CompoundEntityRef;\n  entityMetadata: AsyncState<TechDocsEntityMetadata>;\n  shadowRoot?: ShadowRoot;\n  setShadowRoot: Dispatch<SetStateAction<ShadowRoot | undefined>>;\n  title: string;\n  setTitle: Dispatch<SetStateAction<string>>;\n  subtitle: string;\n  setSubtitle: Dispatch<SetStateAction<string>>;\n  /**\n   * @deprecated property can be passed down directly to the `TechDocsReaderPageContent` instead.\n   */\n  onReady?: () => void;\n};\n\n/**\n * @alpha\n */\nexport const defaultTechDocsReaderPageValue: TechDocsReaderPageValue = {\n  title: '',\n  subtitle: '',\n  setTitle: () => {},\n  setSubtitle: () => {},\n  setShadowRoot: () => {},\n  metadata: { loading: true },\n  entityMetadata: { loading: true },\n  entityRef: { kind: '', name: '', namespace: '' },\n};\n\nconst TechDocsReaderPageContext = createVersionedContext<{\n  1: TechDocsReaderPageValue;\n}>('techdocs-reader-page-context');\n\n/**\n * render function for {@link TechDocsReaderPageProvider}\n *\n * @public\n */\nexport type TechDocsReaderPageProviderRenderFunction = (\n  value: TechDocsReaderPageValue,\n) => JSX.Element;\n\n/**\n * Props for {@link TechDocsReaderPageProvider}\n *\n * @public\n */\nexport type TechDocsReaderPageProviderProps = {\n  entityRef: CompoundEntityRef;\n  children: TechDocsReaderPageProviderRenderFunction | ReactNode;\n};\n\n/**\n * A context to store the reader page state\n * @public\n */\nexport const TechDocsReaderPageProvider = memo(\n  ({ entityRef, children }: TechDocsReaderPageProviderProps) => {\n    const techdocsApi = useApi(techdocsApiRef);\n\n    const metadata = useAsync(async () => {\n      return techdocsApi.getTechDocsMetadata(entityRef);\n    }, [entityRef]);\n\n    const entityMetadata = useAsync(async () => {\n      return techdocsApi.getEntityMetadata(entityRef);\n    }, [entityRef]);\n\n    const [title, setTitle] = useState(defaultTechDocsReaderPageValue.title);\n    const [subtitle, setSubtitle] = useState(\n      defaultTechDocsReaderPageValue.subtitle,\n    );\n    const [shadowRoot, setShadowRoot] = useState<ShadowRoot | undefined>(\n      defaultTechDocsReaderPageValue.shadowRoot,\n    );\n\n    const value = {\n      metadata,\n      entityRef,\n      entityMetadata,\n      shadowRoot,\n      setShadowRoot,\n      title,\n      setTitle,\n      subtitle,\n      setSubtitle,\n    };\n    const versionedValue = createVersionedValueMap({ 1: value });\n\n    return (\n      <TechDocsReaderPageContext.Provider value={versionedValue}>\n        {children instanceof Function ? children(value) : children}\n      </TechDocsReaderPageContext.Provider>\n    );\n  },\n  (prevProps, nextProps) => {\n    return areEntityRefsEqual(prevProps.entityRef, nextProps.entityRef);\n  },\n);\n\n/**\n * Hook used to get access to shared state between reader page components.\n * @alpha\n */\nexport const useTechDocsReaderPage = () => {\n  const versionedContext = useContext(TechDocsReaderPageContext);\n\n  if (versionedContext === undefined) {\n    return defaultTechDocsReaderPageValue;\n  }\n\n  const context = versionedContext.atVersion(1);\n  if (context === undefined) {\n    throw new Error('No context found for version 1.');\n  }\n\n  return context;\n};\n","/*\n * Copyright 2022 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 */\nimport { useState, useEffect, useMemo } from 'react';\nimport debounce from 'lodash/debounce';\nimport { useTechDocsReaderPage } from './context';\n\n/**\n * Hook for use within TechDocs addons that provides access to the underlying\n * shadow root of the current page, allowing the DOM within to be mutated.\n * @alpha\n */\nexport const useShadowRoot = () => {\n  const { shadowRoot } = useTechDocsReaderPage();\n  return shadowRoot;\n};\n\n/**\n * Convenience hook for use within TechDocs addons that provides access to\n * elements that match a given selector within the shadow root.\n *\n * @alpha\n */\nexport const useShadowRootElements = <\n  TReturnedElement extends HTMLElement = HTMLElement,\n>(\n  selectors: string[],\n): TReturnedElement[] => {\n  const shadowRoot = useShadowRoot();\n  if (!shadowRoot) return [];\n  return selectors\n    .map(selector => shadowRoot?.querySelectorAll<TReturnedElement>(selector))\n    .filter(nodeList => nodeList.length)\n    .map(nodeList => Array.from(nodeList))\n    .flat();\n};\n\nconst isValidSelection = (newSelection: Selection) => {\n  // Safari sets the selection rect to top zero\n  return (\n    newSelection.toString() &&\n    newSelection.rangeCount &&\n    newSelection.getRangeAt(0).getBoundingClientRect().top\n  );\n};\n\n/**\n * Hook for retreiving a selection within the ShadowRoot.\n * @alpha\n */\nexport const useShadowRootSelection = (wait: number = 0) => {\n  const shadowRoot = useShadowRoot();\n  const [selection, setSelection] = useState<Selection | null>(null);\n  const handleSelectionChange = useMemo(\n    () =>\n      debounce(() => {\n        const shadowDocument = shadowRoot as ShadowRoot &\n          Pick<Document, 'getSelection'>;\n        // Firefox and Safari don't implement getSelection for Shadow DOM\n        const newSelection = shadowDocument.getSelection\n          ? shadowDocument.getSelection()\n          : document.getSelection();\n\n        if (newSelection && isValidSelection(newSelection)) {\n          setSelection(newSelection);\n        } else {\n          setSelection(null);\n        }\n      }, wait),\n    [shadowRoot, setSelection, wait],\n  );\n\n  useEffect(() => {\n    window.document.addEventListener('selectionchange', handleSelectionChange);\n    return () =>\n      window.document.removeEventListener(\n        'selectionchange',\n        handleSelectionChange,\n      );\n  }, [handleSelectionChange]);\n\n  return selection;\n};\n","/*\n * Copyright 2022 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 { ComponentType } from 'react';\nimport { Entity } from '@backstage/catalog-model';\n\n/**\n * Metadata for TechDocs page\n *\n * @public\n */\nexport type TechDocsMetadata = {\n  site_name: string;\n  site_description: string;\n};\n\n/**\n * Metadata for TechDocs Entity\n *\n * @public\n */\nexport type TechDocsEntityMetadata = Entity & {\n  locationMetadata?: { type: string; target: string };\n};\n\n/**\n * Locations for which TechDocs addons may be declared and rendered.\n * @alpha\n */\nexport const TechDocsAddonLocations = Object.freeze({\n  /**\n   * These addons fill up the header from the right, on the same line as the\n   * title.\n   */\n  Header: 'Header',\n\n  /**\n   * These addons appear below the header and above all content; tooling addons\n   * can be inserted for convenience.\n   */\n  Subheader: 'Subheader',\n\n  /**\n   * These addons are items added to the settings menu list and are designed to make\n   * the reader experience customizable, for example accessibility options\n   */\n  Settings: 'Settings',\n\n  /**\n   * These addons appear left of the content and above the navigation.\n   */\n  PrimarySidebar: 'PrimarySidebar',\n\n  /**\n   * These addons appear right of the content and above the table of contents.\n   */\n  SecondarySidebar: 'SecondarySidebar',\n\n  /**\n   * A virtual location which allows mutation of all content within the shadow\n   * root by transforming DOM nodes. These addons should return null on render.\n   */\n  Content: 'Content',\n\n  /**\n   * todo(backstage/community): This is a proposed virtual location which would\n   * help implement a common addon pattern in which many instances of a given\n   * element in markdown would be dynamically replaced at render-time based on\n   * attributes provided on that element, for example:\n   *\n   * ```md\n   * ## For Fun\n   * <TechDocsAddon>CatGif</TechDocsAddon>\n   *\n   * ## Component Metadata\n   * <TechDocsAddon entityRef=\"default:component/some-component-name\">CatalogEntityCard</TechDocsAddon>\n   *\n   * ## System Metadata\n   * <TechDocsAddon entityRef=\"default:system/some-system-name\">CatalogEntityCard</TechDocsAddon>\n   * ```\n   *\n   * Could correspond to a TechDocs addon named `CatalogEntityCard` with\n   * location `TechDocsAddonLocations.COMPONENT`, whose `component` would be\n   * the react component that would be rendered in place of all instances of\n   * the markdown illustrated above.\n   *\n   * The `@backstage/plugin-techdocs-react` package would need to be updated to, in\n   * cases where such addons had been registered, find all instances of the\n   * the `<TechDocsAddon>` tag whose `textContent` corresponded with the name of the\n   * addon, then replace them with component instances of the addon component,\n   * passing any attributes from the tag as props to the component.\n   */\n  // Component: 'Component',\n} as const);\n\n/**\n * Options for creating a TechDocs addon.\n * @alpha\n */\nexport type TechDocsAddonOptions<TAddonProps = {}> = {\n  name: string;\n  location: keyof typeof TechDocsAddonLocations;\n  component: ComponentType<TAddonProps>;\n};\n"],"names":[],"mappings":";;;;;;;;AAOO,MAAM,mBAAmB,GAAG,0BAA0B,CAAC;AAClD,MAAC,2BAA2B,GAAG,6BAA6B;AAC5D,MAAC,cAAc,GAAG,MAAM,KAAK;AACzC,mBAAmB,CAAC,cAAc,EAAE,2BAA2B,EAAE,IAAI,CAAC,CAAC;AACvE,MAAM,gBAAgB,GAAG,CAAC,IAAI,KAAK;AACnC,EAAE,OAAO,CAAC,EAAE,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACrE,CAAC,CAAC;AACK,SAAS,4BAA4B,CAAC,OAAO,EAAE;AACtD,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;AACrD,EAAE,OAAO,oBAAoB,CAAC;AAC9B,IAAI,IAAI;AACR,IAAI,SAAS,EAAE;AACf,MAAM,IAAI,EAAE,CAAC,KAAK,qBAAqB,KAAK,CAAC,aAAa,CAAC,aAAa,EAAE;AAC1E,QAAQ,GAAG,KAAK;AAChB,OAAO,CAAC;AACR,KAAK;AACL,IAAI,IAAI,EAAE;AACV,MAAM,CAAC,mBAAmB,GAAG,OAAO;AACpC,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,IAAI;AACpC,KAAK;AACL,GAAG,CAAC,CAAC;AACL,CAAC;AACD,MAAM,sBAAsB,GAAG,CAAC,UAAU,EAAE,GAAG,KAAK;AACpD,EAAE,OAAO,UAAU,CAAC,qBAAqB,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC,CAAC;AACF,MAAM,oBAAoB,GAAG,CAAC,UAAU,KAAK;AAC7C,EAAE,OAAO,UAAU,CAAC,qBAAqB,CAAC;AAC1C,IAAI,GAAG,EAAE,2BAA2B;AACpC,GAAG,CAAC,CAAC,qBAAqB,CAAC;AAC3B,IAAI,GAAG,EAAE,mBAAmB;AAC5B,GAAG,CAAC,CAAC;AACL,CAAC,CAAC;AACF,MAAM,wBAAwB,GAAG,CAAC,UAAU,KAAK;AACjD,EAAE,OAAO,UAAU,CAAC,qBAAqB,CAAC;AAC1C,IAAI,GAAG,EAAE,2BAA2B;AACpC,GAAG,CAAC,CAAC,iBAAiB,CAAC;AACvB,IAAI,GAAG,EAAE,mBAAmB;AAC5B,GAAG,CAAC,CAAC;AACL,CAAC,CAAC;AACU,MAAC,iBAAiB,GAAG,MAAM;AACvC,EAAE,MAAM,IAAI,GAAG,SAAS,EAAE,CAAC;AAC3B,EAAE,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;AAClE,EAAE,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;AACnE,EAAE,MAAM,eAAe,GAAG,WAAW,CAAC,CAAC,IAAI,KAAK;AAChD,IAAI,IAAI,EAAE,CAAC;AACX,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI;AAC5B,MAAM,OAAO,IAAI,CAAC;AAClB,IAAI,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChD,IAAI,OAAO,CAAC,EAAE,GAAG,sBAAsB,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC;AAClF,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;AACnB,EAAE,MAAM,qBAAqB,GAAG,WAAW,CAAC,CAAC,IAAI,KAAK;AACtD,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAChE,IAAI,OAAO,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAC/C,GAAG,EAAE,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;AACjC,EAAE,MAAM,0BAA0B,GAAG,WAAW,CAAC,CAAC,QAAQ,KAAK;AAC/D,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;AAC1E,IAAI,OAAO,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC;AAC1D,GAAG,EAAE,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;AACjC,EAAE,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,CAAC;AAC/D;;ACjEY,MAAC,cAAc,GAAG,YAAY,CAAC;AAC3C,EAAE,EAAE,EAAE,yBAAyB;AAC/B,CAAC,EAAE;AACS,MAAC,qBAAqB,GAAG,YAAY,CAAC;AAClD,EAAE,EAAE,EAAE,gCAAgC;AACtC,CAAC;;ACSD,MAAM,kBAAkB,GAAG,CAAC,aAAa,EAAE,aAAa,KAAK;AAC7D,EAAE,OAAO,kBAAkB,CAAC,aAAa,CAAC,KAAK,kBAAkB,CAAC,aAAa,CAAC,CAAC;AACjF,CAAC,CAAC;AACU,MAAC,8BAA8B,GAAG;AAC9C,EAAE,KAAK,EAAE,EAAE;AACX,EAAE,QAAQ,EAAE,EAAE;AACd,EAAE,QAAQ,EAAE,MAAM;AAClB,GAAG;AACH,EAAE,WAAW,EAAE,MAAM;AACrB,GAAG;AACH,EAAE,aAAa,EAAE,MAAM;AACvB,GAAG;AACH,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;AAC7B,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;AACnC,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;AAClD,EAAE;AACF,MAAM,yBAAyB,GAAG,sBAAsB,CAAC,8BAA8B,CAAC,CAAC;AAC7E,MAAC,0BAA0B,GAAG,IAAI,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK;AAC5E,EAAE,MAAM,WAAW,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AAC7C,EAAE,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY;AACxC,IAAI,OAAO,WAAW,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC;AACtD,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;AAClB,EAAE,MAAM,cAAc,GAAG,QAAQ,CAAC,YAAY;AAC9C,IAAI,OAAO,WAAW,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;AACpD,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;AAClB,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAC,8BAA8B,CAAC,KAAK,CAAC,CAAC;AAC3E,EAAE,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,8BAA8B,CAAC,QAAQ,CAAC,CAAC;AACpF,EAAE,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAC,8BAA8B,CAAC,UAAU,CAAC,CAAC;AAC1F,EAAE,MAAM,KAAK,GAAG;AAChB,IAAI,QAAQ;AACZ,IAAI,SAAS;AACb,IAAI,cAAc;AAClB,IAAI,UAAU;AACd,IAAI,aAAa;AACjB,IAAI,KAAK;AACT,IAAI,QAAQ;AACZ,IAAI,QAAQ;AACZ,IAAI,WAAW;AACf,GAAG,CAAC;AACJ,EAAE,MAAM,cAAc,GAAG,uBAAuB,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC/D,EAAE,uBAAuB,KAAK,CAAC,aAAa,CAAC,yBAAyB,CAAC,QAAQ,EAAE;AACjF,IAAI,KAAK,EAAE,cAAc;AACzB,GAAG,EAAE,QAAQ,YAAY,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,CAAC;AAChE,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK;AAC7B,EAAE,OAAO,kBAAkB,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;AACtE,CAAC,EAAE;AACS,MAAC,qBAAqB,GAAG,MAAM;AAC3C,EAAE,MAAM,gBAAgB,GAAG,UAAU,CAAC,yBAAyB,CAAC,CAAC;AACjE,EAAE,IAAI,gBAAgB,KAAK,KAAK,CAAC,EAAE;AACnC,IAAI,OAAO,8BAA8B,CAAC;AAC1C,GAAG;AACH,EAAE,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAChD,EAAE,IAAI,OAAO,KAAK,KAAK,CAAC,EAAE;AAC1B,IAAI,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;AACvD,GAAG;AACH,EAAE,OAAO,OAAO,CAAC;AACjB;;ACpEY,MAAC,aAAa,GAAG,MAAM;AACnC,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,qBAAqB,EAAE,CAAC;AACjD,EAAE,OAAO,UAAU,CAAC;AACpB,EAAE;AACU,MAAC,qBAAqB,GAAG,CAAC,SAAS,KAAK;AACpD,EAAE,MAAM,UAAU,GAAG,aAAa,EAAE,CAAC;AACrC,EAAE,IAAI,CAAC,UAAU;AACjB,IAAI,OAAO,EAAE,CAAC;AACd,EAAE,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,KAAK,UAAU,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,UAAU,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,KAAK,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC/L,EAAE;AACF,MAAM,gBAAgB,GAAG,CAAC,YAAY,KAAK;AAC3C,EAAE,OAAO,YAAY,CAAC,QAAQ,EAAE,IAAI,YAAY,CAAC,UAAU,IAAI,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAC,GAAG,CAAC;AACtH,CAAC,CAAC;AACU,MAAC,sBAAsB,GAAG,CAAC,IAAI,GAAG,CAAC,KAAK;AACpD,EAAE,MAAM,UAAU,GAAG,aAAa,EAAE,CAAC;AACrC,EAAE,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;AACnD,EAAE,MAAM,qBAAqB,GAAG,OAAO,CAAC,MAAM,QAAQ,CAAC,MAAM;AAC7D,IAAI,MAAM,cAAc,GAAG,UAAU,CAAC;AACtC,IAAI,MAAM,YAAY,GAAG,cAAc,CAAC,YAAY,GAAG,cAAc,CAAC,YAAY,EAAE,GAAG,QAAQ,CAAC,YAAY,EAAE,CAAC;AAC/G,IAAI,IAAI,YAAY,IAAI,gBAAgB,CAAC,YAAY,CAAC,EAAE;AACxD,MAAM,YAAY,CAAC,YAAY,CAAC,CAAC;AACjC,KAAK,MAAM;AACX,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;AACzB,KAAK;AACL,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC;AAC9C,EAAE,SAAS,CAAC,MAAM;AAClB,IAAI,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,iBAAiB,EAAE,qBAAqB,CAAC,CAAC;AAC/E,IAAI,OAAO,MAAM,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,iBAAiB,EAAE,qBAAqB,CAAC,CAAC;AAC/F,GAAG,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC;AAC9B,EAAE,OAAO,SAAS,CAAC;AACnB;;ACjCY,MAAC,sBAAsB,GAAG,MAAM,CAAC,MAAM,CAAC;AACpD,EAAE,MAAM,EAAE,QAAQ;AAClB,EAAE,SAAS,EAAE,WAAW;AACxB,EAAE,QAAQ,EAAE,UAAU;AACtB,EAAE,cAAc,EAAE,gBAAgB;AAClC,EAAE,gBAAgB,EAAE,kBAAkB;AACtC,EAAE,OAAO,EAAE,SAAS;AACpB,CAAC;;;;"}
+{"version":3,"file":"index.esm.js","sources":["../src/addons.tsx","../src/api.ts","../src/context.tsx","../src/types.ts","../src/component.tsx","../src/hooks.ts"],"sourcesContent":["/*\n * Copyright 2022 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, { useCallback } from 'react';\nimport { useOutlet } from 'react-router-dom';\n\nimport {\n  attachComponentData,\n  createReactExtension,\n  ElementCollection,\n  Extension,\n  useElementFilter,\n} from '@backstage/core-plugin-api';\n\nimport { TechDocsAddonLocations, TechDocsAddonOptions } from './types';\n\nexport const TECHDOCS_ADDONS_KEY = 'techdocs.addons.addon.v1';\n\n/**\n * Marks the <TechDocsAddons> registry component.\n * @public\n */\nexport const TECHDOCS_ADDONS_WRAPPER_KEY = 'techdocs.addons.wrapper.v1';\n\n/**\n * TechDocs Addon registry.\n * @public\n */\nexport const TechDocsAddons: React.ComponentType = () => null;\n\nattachComponentData(TechDocsAddons, TECHDOCS_ADDONS_WRAPPER_KEY, true);\n\nconst getDataKeyByName = (name: string) => {\n  return `${TECHDOCS_ADDONS_KEY}.${name.toLocaleLowerCase('en-US')}`;\n};\n\n/**\n * Create a TechDocs addon overload signature without props.\n * @public\n */\nexport function createTechDocsAddonExtension(\n  options: TechDocsAddonOptions,\n): Extension<() => JSX.Element | null>;\n\n/**\n * Create a TechDocs addon overload signature with props.\n * @public\n */\nexport function createTechDocsAddonExtension<TComponentProps>(\n  options: TechDocsAddonOptions<TComponentProps>,\n): Extension<(props: TComponentProps) => JSX.Element | null>;\n\n/**\n * Create a TechDocs addon implementation.\n * @public\n */\nexport function createTechDocsAddonExtension<TComponentProps>(\n  options: TechDocsAddonOptions<TComponentProps>,\n): Extension<(props: TComponentProps) => JSX.Element | null> {\n  const { name, component: TechDocsAddon } = options;\n  return createReactExtension({\n    name,\n    component: {\n      sync: (props: TComponentProps) => <TechDocsAddon {...props} />,\n    },\n    data: {\n      [TECHDOCS_ADDONS_KEY]: options,\n      [getDataKeyByName(name)]: true,\n    },\n  });\n}\n\nconst getTechDocsAddonByName = (\n  collection: ElementCollection,\n  key: string,\n): JSX.Element | undefined => {\n  return collection.selectByComponentData({ key }).getElements()[0];\n};\n\nconst getAllTechDocsAddons = (collection: ElementCollection) => {\n  return collection\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_WRAPPER_KEY,\n    })\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_KEY,\n    });\n};\n\nconst getAllTechDocsAddonsData = (collection: ElementCollection) => {\n  return collection\n    .selectByComponentData({\n      key: TECHDOCS_ADDONS_WRAPPER_KEY,\n    })\n    .findComponentData<TechDocsAddonOptions>({\n      key: TECHDOCS_ADDONS_KEY,\n    });\n};\n\n/**\n * hook to use addons in components\n * @public\n */\nexport const useTechDocsAddons = () => {\n  const node = useOutlet();\n  const collection = useElementFilter(node, getAllTechDocsAddons);\n  const options = useElementFilter(node, getAllTechDocsAddonsData);\n\n  const findAddonByData = useCallback(\n    (data: TechDocsAddonOptions | undefined) => {\n      if (!collection || !data) return null;\n      const nameKey = getDataKeyByName(data.name);\n      return getTechDocsAddonByName(collection, nameKey) ?? null;\n    },\n    [collection],\n  );\n\n  const renderComponentByName = useCallback(\n    (name: string) => {\n      const data = options.find(option => option.name === name);\n      return data ? findAddonByData(data) : null;\n    },\n    [options, findAddonByData],\n  );\n\n  const renderComponentsByLocation = useCallback(\n    (location: keyof typeof TechDocsAddonLocations) => {\n      const data = options.filter(option => option.location === location);\n      return data.length ? data.map(findAddonByData) : null;\n    },\n    [options, findAddonByData],\n  );\n\n  return { renderComponentByName, renderComponentsByLocation };\n};\n","/*\n * Copyright 2022 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 { CompoundEntityRef } from '@backstage/catalog-model';\nimport { createApiRef } from '@backstage/core-plugin-api';\nimport { TechDocsEntityMetadata, TechDocsMetadata } from './types';\n\n/**\n * API to talk to techdocs-backend.\n *\n * @public\n */\nexport interface TechDocsApi {\n  getApiOrigin(): Promise<string>;\n  getTechDocsMetadata(entityId: CompoundEntityRef): Promise<TechDocsMetadata>;\n  getEntityMetadata(\n    entityId: CompoundEntityRef,\n  ): Promise<TechDocsEntityMetadata>;\n}\n\n/**\n * Utility API reference for the {@link TechDocsApi}.\n *\n * @public\n */\nexport const techdocsApiRef = createApiRef<TechDocsApi>({\n  id: 'plugin.techdocs.service',\n});\n\n/**\n * The outcome of a docs sync operation.\n *\n * @public\n */\nexport type SyncResult = 'cached' | 'updated';\n\n/**\n * API which talks to TechDocs storage to fetch files to render.\n *\n * @public\n */\nexport interface TechDocsStorageApi {\n  getApiOrigin(): Promise<string>;\n  getStorageUrl(): Promise<string>;\n  getBuilder(): Promise<string>;\n  getEntityDocs(entityId: CompoundEntityRef, path: string): Promise<string>;\n  syncEntityDocs(\n    entityId: CompoundEntityRef,\n    logHandler?: (line: string) => void,\n  ): Promise<SyncResult>;\n  getBaseUrl(\n    oldBaseUrl: string,\n    entityId: CompoundEntityRef,\n    path: string,\n  ): Promise<string>;\n}\n\n/**\n * Utility API reference for the {@link TechDocsStorageApi}.\n *\n * @public\n */\nexport const techdocsStorageApiRef = createApiRef<TechDocsStorageApi>({\n  id: 'plugin.techdocs.storageservice',\n});\n","/*\n * Copyright 2022 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, {\n  Dispatch,\n  SetStateAction,\n  useContext,\n  useState,\n  memo,\n  ReactNode,\n} from 'react';\nimport useAsync, { AsyncState } from 'react-use/lib/useAsync';\n\nimport {\n  CompoundEntityRef,\n  stringifyEntityRef,\n} from '@backstage/catalog-model';\nimport {\n  createVersionedContext,\n  createVersionedValueMap,\n} from '@backstage/version-bridge';\n\nimport { useApi } from '@backstage/core-plugin-api';\n\nimport { techdocsApiRef } from './api';\nimport { TechDocsEntityMetadata, TechDocsMetadata } from './types';\n\nconst areEntityRefsEqual = (\n  prevEntityRef: CompoundEntityRef,\n  nextEntityRef: CompoundEntityRef,\n) => {\n  return (\n    stringifyEntityRef(prevEntityRef) === stringifyEntityRef(nextEntityRef)\n  );\n};\n\n/**\n * @public type for the value of the TechDocsReaderPageContext\n */\nexport type TechDocsReaderPageValue = {\n  metadata: AsyncState<TechDocsMetadata>;\n  entityRef: CompoundEntityRef;\n  entityMetadata: AsyncState<TechDocsEntityMetadata>;\n  shadowRoot?: ShadowRoot;\n  setShadowRoot: Dispatch<SetStateAction<ShadowRoot | undefined>>;\n  title: string;\n  setTitle: Dispatch<SetStateAction<string>>;\n  subtitle: string;\n  setSubtitle: Dispatch<SetStateAction<string>>;\n  /**\n   * @deprecated property can be passed down directly to the `TechDocsReaderPageContent` instead.\n   */\n  onReady?: () => void;\n};\n\nconst defaultTechDocsReaderPageValue: TechDocsReaderPageValue = {\n  title: '',\n  subtitle: '',\n  setTitle: () => {},\n  setSubtitle: () => {},\n  setShadowRoot: () => {},\n  metadata: { loading: true },\n  entityMetadata: { loading: true },\n  entityRef: { kind: '', name: '', namespace: '' },\n};\n\nconst TechDocsReaderPageContext = createVersionedContext<{\n  1: TechDocsReaderPageValue;\n}>('techdocs-reader-page-context');\n\n/**\n * render function for {@link TechDocsReaderPageProvider}\n *\n * @public\n */\nexport type TechDocsReaderPageProviderRenderFunction = (\n  value: TechDocsReaderPageValue,\n) => JSX.Element;\n\n/**\n * Props for {@link TechDocsReaderPageProvider}\n *\n * @public\n */\nexport type TechDocsReaderPageProviderProps = {\n  entityRef: CompoundEntityRef;\n  children: TechDocsReaderPageProviderRenderFunction | ReactNode;\n};\n\n/**\n * A context to store the reader page state\n * @public\n */\nexport const TechDocsReaderPageProvider = memo(\n  ({ entityRef, children }: TechDocsReaderPageProviderProps) => {\n    const techdocsApi = useApi(techdocsApiRef);\n\n    const metadata = useAsync(async () => {\n      return techdocsApi.getTechDocsMetadata(entityRef);\n    }, [entityRef]);\n\n    const entityMetadata = useAsync(async () => {\n      return techdocsApi.getEntityMetadata(entityRef);\n    }, [entityRef]);\n\n    const [title, setTitle] = useState(defaultTechDocsReaderPageValue.title);\n    const [subtitle, setSubtitle] = useState(\n      defaultTechDocsReaderPageValue.subtitle,\n    );\n    const [shadowRoot, setShadowRoot] = useState<ShadowRoot | undefined>(\n      defaultTechDocsReaderPageValue.shadowRoot,\n    );\n\n    const value = {\n      metadata,\n      entityRef,\n      entityMetadata,\n      shadowRoot,\n      setShadowRoot,\n      title,\n      setTitle,\n      subtitle,\n      setSubtitle,\n    };\n    const versionedValue = createVersionedValueMap({ 1: value });\n\n    return (\n      <TechDocsReaderPageContext.Provider value={versionedValue}>\n        {children instanceof Function ? children(value) : children}\n      </TechDocsReaderPageContext.Provider>\n    );\n  },\n  (prevProps, nextProps) => {\n    return areEntityRefsEqual(prevProps.entityRef, nextProps.entityRef);\n  },\n);\n\n/**\n * Hook used to get access to shared state between reader page components.\n * @public\n */\nexport const useTechDocsReaderPage = () => {\n  const versionedContext = useContext(TechDocsReaderPageContext);\n\n  if (versionedContext === undefined) {\n    return defaultTechDocsReaderPageValue;\n  }\n\n  const context = versionedContext.atVersion(1);\n  if (context === undefined) {\n    throw new Error('No context found for version 1.');\n  }\n\n  return context;\n};\n","/*\n * Copyright 2022 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 { ComponentType } from 'react';\nimport { Entity } from '@backstage/catalog-model';\n\n/**\n * Metadata for TechDocs page\n *\n * @public\n */\nexport type TechDocsMetadata = {\n  site_name: string;\n  site_description: string;\n};\n\n/**\n * Metadata for TechDocs Entity\n *\n * @public\n */\nexport type TechDocsEntityMetadata = Entity & {\n  locationMetadata?: { type: string; target: string };\n};\n\n/**\n * Locations for which TechDocs addons may be declared and rendered.\n * @public\n */\nexport const TechDocsAddonLocations = Object.freeze({\n  /**\n   * These addons fill up the header from the right, on the same line as the\n   * title.\n   */\n  Header: 'Header',\n\n  /**\n   * These addons appear below the header and above all content; tooling addons\n   * can be inserted for convenience.\n   */\n  Subheader: 'Subheader',\n\n  /**\n   * These addons are items added to the settings menu list and are designed to make\n   * the reader experience customizable, for example accessibility options\n   */\n  Settings: 'Settings',\n\n  /**\n   * These addons appear left of the content and above the navigation.\n   */\n  PrimarySidebar: 'PrimarySidebar',\n\n  /**\n   * These addons appear right of the content and above the table of contents.\n   */\n  SecondarySidebar: 'SecondarySidebar',\n\n  /**\n   * A virtual location which allows mutation of all content within the shadow\n   * root by transforming DOM nodes. These addons should return null on render.\n   */\n  Content: 'Content',\n\n  /**\n   * todo(backstage/community): This is a proposed virtual location which would\n   * help implement a common addon pattern in which many instances of a given\n   * element in markdown would be dynamically replaced at render-time based on\n   * attributes provided on that element, for example:\n   *\n   * ```md\n   * ## For Fun\n   * <TechDocsAddon>CatGif</TechDocsAddon>\n   *\n   * ## Component Metadata\n   * <TechDocsAddon entityRef=\"default:component/some-component-name\">CatalogEntityCard</TechDocsAddon>\n   *\n   * ## System Metadata\n   * <TechDocsAddon entityRef=\"default:system/some-system-name\">CatalogEntityCard</TechDocsAddon>\n   * ```\n   *\n   * Could correspond to a TechDocs addon named `CatalogEntityCard` with\n   * location `TechDocsAddonLocations.COMPONENT`, whose `component` would be\n   * the react component that would be rendered in place of all instances of\n   * the markdown illustrated above.\n   *\n   * The `@backstage/plugin-techdocs-react` package would need to be updated to, in\n   * cases where such addons had been registered, find all instances of the\n   * the `<TechDocsAddon>` tag whose `textContent` corresponded with the name of the\n   * addon, then replace them with component instances of the addon component,\n   * passing any attributes from the tag as props to the component.\n   */\n  // Component: 'Component',\n} as const);\n\n/**\n * Options for creating a TechDocs addon.\n * @public\n */\nexport type TechDocsAddonOptions<TAddonProps = {}> = {\n  name: string;\n  location: keyof typeof TechDocsAddonLocations;\n  component: ComponentType<TAddonProps>;\n};\n","/*\n * Copyright 2022 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, {\n  PropsWithChildren,\n  useState,\n  useEffect,\n  useCallback,\n} from 'react';\n\nimport { create } from 'jss';\nimport { StylesProvider, jssPreset } from '@material-ui/styles';\n\nimport { Progress } from '@backstage/core-components';\n\n/**\n * Name for the event dispatched when ShadowRoot styles are loaded.\n * @public\n */\nexport const SHADOW_DOM_STYLE_LOAD_EVENT = 'TECH_DOCS_SHADOW_DOM_STYLE_LOAD';\n\n/**\n * Dispatch style load event after all styles are loaded.\n * @param element - the ShadowRoot tree.\n */\nconst useShadowDomStylesEvents = (element: Element | null) => {\n  useEffect(() => {\n    if (!element) {\n      return () => {};\n    }\n\n    const styles = element.querySelectorAll<HTMLElement>(\n      'head > link[rel=\"stylesheet\"]',\n    );\n\n    let count = styles?.length ?? 0;\n    const event = new CustomEvent(SHADOW_DOM_STYLE_LOAD_EVENT);\n\n    if (!count) {\n      element.dispatchEvent(event);\n      return () => {};\n    }\n\n    const handleLoad = () => {\n      if (--count === 0) {\n        element.dispatchEvent(event);\n      }\n    };\n\n    styles?.forEach(style => {\n      style.addEventListener('load', handleLoad);\n    });\n\n    return () => {\n      styles?.forEach(style => {\n        style.removeEventListener('load', handleLoad);\n      });\n    };\n  }, [element]);\n};\n\n/**\n * Returns the style's loading state.\n *\n * @example\n * Here's an example that updates the sidebar position only after styles are calculated:\n * ```jsx\n * import {\n *   TechDocsShadowDom,\n *   useShadowDomStylesLoading,\n * } from '@backstage/plugin-techdocs-react';\n *\n * export const TechDocsReaderPageContent = () => {\n *   // ...\n *   const dom = useTechDocsReaderDom(entity);\n *   const isStyleLoading = useShadowDomStylesLoading(dom);\n *\n *   const updateSidebarPosition = useCallback(() => {\n *     //...\n *   }, [dom]);\n *\n *   useEffect(() => {\n *     if (!isStyleLoading) {\n *       updateSidebarPosition();\n *     }\n *   }, [isStyleLoading, updateSidebarPosition]);\n *\n *   const handleDomAppend = useCallback(\n *     (newShadowRoot: ShadowRoot) => {\n *       setShadowRoot(newShadowRoot);\n *     },\n *     [setShadowRoot],\n *   );\n *\n *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;\n * };\n * ```\n *\n * @param element - which is the ShadowRoot tree.\n * @returns a boolean value, true if styles are being loaded.\n * @public\n */\nexport const useShadowDomStylesLoading = (element: Element | null) => {\n  const [loading, setLoading] = useState(false);\n\n  useEffect(() => {\n    if (!element) return () => {};\n\n    setLoading(true);\n\n    const style = (element as HTMLElement).style;\n\n    style.setProperty('opacity', '0');\n\n    const handleLoad = () => {\n      setLoading(false);\n      style.setProperty('opacity', '1');\n    };\n\n    element.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, handleLoad);\n\n    return () => {\n      element.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, handleLoad);\n    };\n  }, [element]);\n\n  return loading;\n};\n\n/**\n * Props for {@link TechDocsShadowDom}.\n *\n * @remarks\n * If you want to use portals to render Material UI components in the Shadow DOM,\n * you must render these portals as children because this component wraps its children in a Material UI StylesProvider\n * to ensure that Material UI styles are applied.\n *\n * @public\n */\nexport type TechDocsShadowDomProps = PropsWithChildren<{\n  /**\n   * Element tree that is appended to ShadowRoot.\n   */\n  element: Element;\n  /**\n   * Callback called when the element tree is appended in ShadowRoot.\n   */\n  onAppend?: (shadowRoot: ShadowRoot) => void;\n}>;\n\n/**\n * Renders a tree of elements in a Shadow DOM.\n *\n * @remarks\n * Centers the styles loaded event to avoid having multiple locations setting the opacity style in Shadow DOM causing the screen to flash multiple times,\n * so if you want to know when Shadow DOM styles are computed, you can listen for the \"TECH_DOCS_SHADOW_DOM_STYLE_LOAD\" event dispatched by the element tree.\n *\n * @example\n * Here is an example using this component and also listening for styles loaded event:\n *```jsx\n * import {\n *   TechDocsShadowDom,\n *   SHADOW_DOM_STYLE_LOAD_EVENT,\n * } from '@backstage/plugin-techdocs-react';\n *\n * export const TechDocsReaderPageContent = ({ entity }: TechDocsReaderPageContentProps) => {\n *   // ...\n *   const dom = useTechDocsReaderDom(entity);\n *\n *   useEffect(() => {\n *     const updateSidebarPosition = () => {\n *       // ...\n *     };\n *     dom?.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);\n *     return () => {\n *       dom?.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);\n *     };\n *   }, [dom]);\n *\n *   const handleDomAppend = useCallback(\n *     (newShadowRoot: ShadowRoot) => {\n *       setShadowRoot(newShadowRoot);\n *     },\n *     [setShadowRoot],\n *   );\n *\n *   return <TechDocsShadowDom element={dom} onAppend={handleDomAppend} />;\n * };\n * ```\n *\n * @param props - see {@link TechDocsShadowDomProps}.\n * @public\n */\nexport const TechDocsShadowDom = ({\n  element,\n  onAppend,\n  children,\n}: TechDocsShadowDomProps) => {\n  const [jss, setJss] = useState(\n    create({\n      ...jssPreset(),\n      insertionPoint: undefined,\n    }),\n  );\n\n  useShadowDomStylesEvents(element);\n  const loading = useShadowDomStylesLoading(element);\n\n  const ref = useCallback(\n    (shadowHost: HTMLDivElement) => {\n      if (!element || !shadowHost) return;\n\n      setJss(\n        create({\n          ...jssPreset(),\n          insertionPoint: element.querySelector('head') || undefined,\n        }),\n      );\n\n      let shadowRoot = shadowHost.shadowRoot;\n\n      if (!shadowRoot) {\n        shadowRoot = shadowHost.attachShadow({ mode: 'open' });\n      }\n\n      shadowRoot.replaceChildren(element);\n\n      if (typeof onAppend === 'function') {\n        onAppend(shadowRoot);\n      }\n    },\n    [element, onAppend],\n  );\n\n  return (\n    <>\n      {loading && <Progress />}\n      {/* The sheetsManager={new Map()} is needed in order to deduplicate the injection of CSS in the page. */}\n      <StylesProvider jss={jss} sheetsManager={new Map()}>\n        <div ref={ref} data-testid=\"techdocs-native-shadowroot\" />\n        {children}\n      </StylesProvider>\n    </>\n  );\n};\n","/*\n * Copyright 2022 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 */\nimport { useState, useEffect, useMemo } from 'react';\nimport debounce from 'lodash/debounce';\nimport { useTechDocsReaderPage } from './context';\n\n/**\n * Hook for use within TechDocs addons that provides access to the underlying\n * shadow root of the current page, allowing the DOM within to be mutated.\n * @public\n */\nexport const useShadowRoot = () => {\n  const { shadowRoot } = useTechDocsReaderPage();\n  return shadowRoot;\n};\n\n/**\n * Convenience hook for use within TechDocs addons that provides access to\n * elements that match a given selector within the shadow root.\n *\n * @public\n */\nexport const useShadowRootElements = <\n  TReturnedElement extends HTMLElement = HTMLElement,\n>(\n  selectors: string[],\n): TReturnedElement[] => {\n  const shadowRoot = useShadowRoot();\n  if (!shadowRoot) return [];\n  return selectors\n    .map(selector => shadowRoot?.querySelectorAll<TReturnedElement>(selector))\n    .filter(nodeList => nodeList.length)\n    .map(nodeList => Array.from(nodeList))\n    .flat();\n};\n\nconst isValidSelection = (newSelection: Selection) => {\n  // Safari sets the selection rect to top zero\n  return (\n    newSelection.toString() &&\n    newSelection.rangeCount &&\n    newSelection.getRangeAt(0).getBoundingClientRect().top\n  );\n};\n\n/**\n * Hook for retreiving a selection within the ShadowRoot.\n * @public\n */\nexport const useShadowRootSelection = (wait: number = 0) => {\n  const shadowRoot = useShadowRoot();\n  const [selection, setSelection] = useState<Selection | null>(null);\n  const handleSelectionChange = useMemo(\n    () =>\n      debounce(() => {\n        const shadowDocument = shadowRoot as ShadowRoot &\n          Pick<Document, 'getSelection'>;\n        // Firefox and Safari don't implement getSelection for Shadow DOM\n        const newSelection = shadowDocument.getSelection\n          ? shadowDocument.getSelection()\n          : document.getSelection();\n\n        if (newSelection && isValidSelection(newSelection)) {\n          setSelection(newSelection);\n        } else {\n          setSelection(null);\n        }\n      }, wait),\n    [shadowRoot, setSelection, wait],\n  );\n\n  useEffect(() => {\n    window.document.addEventListener('selectionchange', handleSelectionChange);\n    return () =>\n      window.document.removeEventListener(\n        'selectionchange',\n        handleSelectionChange,\n      );\n  }, [handleSelectionChange]);\n\n  return selection;\n};\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-techdocs-react",
   "description": "Shared frontend utilities for TechDocs and Addons",
-  "version": "0.1.1-next.2",
+  "version": "1.0.1-next.1",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -35,9 +35,9 @@
     "start": "backstage-cli package start"
   },
   "dependencies": {
-    "@backstage/catalog-model": "^1.0.2-next.0",
-    "@backstage/core-components": "^0.9.4-next.1",
-    "@backstage/core-plugin-api": "^1.0.2-next.1",
+    "@backstage/catalog-model": "^1.0.3-next.0",
+    "@backstage/core-components": "^0.9.5-next.1",
+    "@backstage/core-plugin-api": "^1.0.3-next.0",
     "@backstage/version-bridge": "^1.0.1",
     "@material-ui/core": "^4.12.2",
     "@material-ui/lab": "4.0.0-alpha.57",
@@ -53,8 +53,9 @@
     "react": "^16.13.1 || ^17.0.0"
   },
   "devDependencies": {
-    "@backstage/test-utils": "^1.1.0-next.2",
+    "@backstage/test-utils": "^1.1.1-next.0",
     "@backstage/theme": "^0.2.15",
+    "@testing-library/jest-dom": "^5.10.1",
     "@testing-library/react": "^12.1.3",
     "@testing-library/react-hooks": "^8.0.0"
   },
@@ -62,5 +63,5 @@
     "alpha",
     "dist"
   ],
-  "gitHead": "cfbf5762d7d91eee18999306b21d63840400ee29"
+  "gitHead": "e15c24ddb5d14034629ced8a5a5d8f12b8f1a7dd"
 }