@backstage/plugin-techdocs-react 1.1.3 → 1.1.4-next.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @backstage/plugin-techdocs-react
 
+## 1.1.4-next.1
+
+### Patch Changes
+
+- 8adfda60ae1: Updated dependency `jss` to `~10.10.0`.
+- Updated dependencies
+  - @backstage/core-components@0.12.5-next.1
+  - @backstage/core-plugin-api@1.4.1-next.1
+  - @backstage/config@1.0.7-next.0
+  - @backstage/catalog-model@1.2.1-next.1
+  - @backstage/version-bridge@1.0.3
+
+## 1.1.4-next.0
+
+### Patch Changes
+
+- 928a12a9b3: Internal refactor of `/alpha` exports.
+- Updated dependencies
+  - @backstage/core-plugin-api@1.4.1-next.0
+  - @backstage/catalog-model@1.2.1-next.0
+  - @backstage/config@1.0.6
+  - @backstage/core-components@0.12.5-next.0
+  - @backstage/version-bridge@1.0.3
+
 ## 1.1.3
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,64 +1,35 @@
-/**
- * Package encapsulating utilities to be shared by frontend TechDocs plugins.
- *
- * @packageDocumentation
- */
-
-import { ApiRef } from '@backstage/core-plugin-api';
+import React, { ComponentType, Dispatch, SetStateAction, ReactNode, PropsWithChildren } from 'react';
+import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
+import { Extension } from '@backstage/core-plugin-api';
+import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
 import { AsyncState } from 'react-use/lib/useAsync';
-import { ComponentType } from 'react';
-import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
-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 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>;
-
-/**
- * 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.
+ * Metadata for TechDocs page
  *
  * @public
  */
-export declare type SyncResult = 'cached' | 'updated';
-
-/**
- * Key for each addon.
- * @public
- */
-export declare const TECHDOCS_ADDONS_KEY = "techdocs.addons.addon.v1";
-
+declare type TechDocsMetadata = {
+    site_name: string;
+    site_description: string;
+};
 /**
- * Marks the `<TechDocsAddons>` registry component.
+ * Metadata for TechDocs Entity
+ *
  * @public
  */
-export declare const TECHDOCS_ADDONS_WRAPPER_KEY = "techdocs.addons.wrapper.v1";
-
+declare type TechDocsEntityMetadata = Entity & {
+    locationMetadata?: {
+        type: string;
+        target: string;
+    };
+};
 /**
  * Locations for which TechDocs addons may be declared and rendered.
  * @public
  */
-export declare const TechDocsAddonLocations: Readonly<{
+declare const TechDocsAddonLocations: Readonly<{
     /**
      * These addons fill up the header from the right, on the same line as the
      * title.
@@ -88,90 +59,96 @@ export declare const TechDocsAddonLocations: Readonly<{
      */
     readonly Content: "Content";
 }>;
-
 /**
  * Options for creating a TechDocs addon.
  * @public
  */
-export declare type TechDocsAddonOptions<TAddonProps = {}> = {
+declare type TechDocsAddonOptions<TAddonProps = {}> = {
     name: string;
     location: keyof typeof TechDocsAddonLocations;
     component: ComponentType<TAddonProps>;
 };
 
+/**
+ * Key for each addon.
+ * @public
+ */
+declare const TECHDOCS_ADDONS_KEY = "techdocs.addons.addon.v1";
+/**
+ * Marks the `<TechDocsAddons>` registry component.
+ * @public
+ */
+declare const TECHDOCS_ADDONS_WRAPPER_KEY = "techdocs.addons.wrapper.v1";
 /**
  * TechDocs Addon registry.
  * @public
  */
-export declare const TechDocsAddons: React_2.ComponentType<React_2.PropsWithChildren<{}>>;
+declare const TechDocsAddons: React.ComponentType<React.PropsWithChildren<{}>>;
+/**
+ * Create a TechDocs addon overload signature without props.
+ * @public
+ */
+declare function createTechDocsAddonExtension(options: TechDocsAddonOptions): Extension<() => JSX.Element | null>;
+/**
+ * Create a TechDocs addon overload signature with props.
+ * @public
+ */
+declare function createTechDocsAddonExtension<TComponentProps>(options: TechDocsAddonOptions<TComponentProps>): Extension<(props: TComponentProps) => JSX.Element | null>;
+/**
+ * hook to use addons in components
+ * @public
+ */
+declare const useTechDocsAddons: () => {
+    renderComponentByName: (name: string) => JSX.Element | null;
+    renderComponentsByLocation: (location: keyof typeof TechDocsAddonLocations) => (JSX.Element | null)[] | null;
+};
 
 /**
  * API to talk to techdocs-backend.
  *
  * @public
  */
-export declare interface TechDocsApi {
+interface TechDocsApi {
     getApiOrigin(): Promise<string>;
     getTechDocsMetadata(entityId: CompoundEntityRef): Promise<TechDocsMetadata>;
     getEntityMetadata(entityId: CompoundEntityRef): Promise<TechDocsEntityMetadata>;
 }
-
 /**
  * Utility API reference for the {@link TechDocsApi}.
  *
  * @public
  */
-export declare const techdocsApiRef: ApiRef<TechDocsApi>;
-
-/**
- * Metadata for TechDocs Entity
- *
- * @public
- */
-export declare type TechDocsEntityMetadata = Entity & {
-    locationMetadata?: {
-        type: string;
-        target: string;
-    };
-};
-
+declare const techdocsApiRef: _backstage_core_plugin_api.ApiRef<TechDocsApi>;
 /**
- * Metadata for TechDocs page
+ * The outcome of a docs sync operation.
  *
  * @public
  */
-export declare type TechDocsMetadata = {
-    site_name: string;
-    site_description: string;
-};
-
-/**
- * A context to store the reader page state
- * @public
- */
-export declare const TechDocsReaderPageProvider: React_2.MemoExoticComponent<({ entityRef, children }: TechDocsReaderPageProviderProps) => JSX.Element>;
-
+declare type SyncResult = 'cached' | 'updated';
 /**
- * Props for {@link TechDocsReaderPageProvider}
+ * API which talks to TechDocs storage to fetch files to render.
  *
  * @public
  */
-export declare type TechDocsReaderPageProviderProps = {
-    entityRef: CompoundEntityRef;
-    children: TechDocsReaderPageProviderRenderFunction | ReactNode;
-};
-
+interface TechDocsStorageApi {
+    getApiOrigin(): Promise<string>;
+    getStorageUrl(): Promise<string>;
+    getBuilder(): Promise<string>;
+    getEntityDocs(entityId: CompoundEntityRef, path: string): Promise<string>;
+    syncEntityDocs(entityId: CompoundEntityRef, logHandler?: (line: string) => void): Promise<SyncResult>;
+    getBaseUrl(oldBaseUrl: string, entityId: CompoundEntityRef, path: string): Promise<string>;
+}
 /**
- * render function for {@link TechDocsReaderPageProvider}
+ * Utility API reference for the {@link TechDocsStorageApi}.
  *
  * @public
  */
-export declare type TechDocsReaderPageProviderRenderFunction = (value: TechDocsReaderPageValue) => JSX.Element;
+declare const techdocsStorageApiRef: _backstage_core_plugin_api.ApiRef<TechDocsStorageApi>;
 
 /**
  * @public type for the value of the TechDocsReaderPageContext
  */
-export declare type TechDocsReaderPageValue = {
+declare type TechDocsReaderPageValue = {
     metadata: AsyncState<TechDocsMetadata>;
     entityRef: CompoundEntityRef;
     entityMetadata: AsyncState<TechDocsEntityMetadata>;
@@ -186,36 +163,63 @@ export declare type TechDocsReaderPageValue = {
      */
     onReady?: () => void;
 };
-
 /**
- * Renders a tree of elements in a Shadow DOM.
+ * render function for {@link TechDocsReaderPageProvider}
  *
- * @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.
+ * @public
+ */
+declare type TechDocsReaderPageProviderRenderFunction = (value: TechDocsReaderPageValue) => JSX.Element;
+/**
+ * Props for {@link TechDocsReaderPageProvider}
+ *
+ * @public
+ */
+declare type TechDocsReaderPageProviderProps = {
+    entityRef: CompoundEntityRef;
+    children: TechDocsReaderPageProviderRenderFunction | ReactNode;
+};
+/**
+ * A context to store the reader page state
+ * @public
+ */
+declare const TechDocsReaderPageProvider: React.MemoExoticComponent<({ entityRef, children }: TechDocsReaderPageProviderProps) => JSX.Element>;
+/**
+ * Hook used to get access to shared state between reader page components.
+ * @public
+ */
+declare const useTechDocsReaderPage: () => TechDocsReaderPageValue;
+
+/**
+ * Name for the event dispatched when ShadowRoot styles are loaded.
+ * @public
+ */
+declare const SHADOW_DOM_STYLE_LOAD_EVENT = "TECH_DOCS_SHADOW_DOM_STYLE_LOAD";
+/**
+ * Returns the style's loading state.
  *
  * @example
- * Here is an example using this component and also listening for styles loaded event:
- *```jsx
+ * Here's an example that updates the sidebar position only after styles are calculated:
+ * ```jsx
  * import {
  *   TechDocsShadowDom,
- *   SHADOW_DOM_STYLE_LOAD_EVENT,
+ *   useShadowDomStylesLoading,
  * } from '@backstage/plugin-techdocs-react';
  *
- * export const TechDocsReaderPageContent = ({ entity }: TechDocsReaderPageContentProps) => {
+ * export const TechDocsReaderPageContent = () => {
  *   // ...
  *   const dom = useTechDocsReaderDom(entity);
+ *   const isStyleLoading = useShadowDomStylesLoading(dom);
  *
- *   useEffect(() => {
- *     const updateSidebarPosition = () => {
- *       // ...
- *     };
- *     dom?.addEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);
- *     return () => {
- *       dom?.removeEventListener(SHADOW_DOM_STYLE_LOAD_EVENT, updateSidebarPosition);
- *     };
+ *   const updateSidebarPosition = useCallback(() => {
+ *     //...
  *   }, [dom]);
  *
+ *   useEffect(() => {
+ *     if (!isStyleLoading) {
+ *       updateSidebarPosition();
+ *     }
+ *   }, [isStyleLoading, updateSidebarPosition]);
+ *
  *   const handleDomAppend = useCallback(
  *     (newShadowRoot: ShadowRoot) => {
  *       setShadowRoot(newShadowRoot);
@@ -227,11 +231,11 @@ export declare type TechDocsReaderPageValue = {
  * };
  * ```
  *
- * @param props - see {@link TechDocsShadowDomProps}.
+ * @param element - which is the ShadowRoot tree.
+ * @returns a boolean value, true if styles are being loaded.
  * @public
  */
-export declare const TechDocsShadowDom: ({ element, onAppend, children, }: TechDocsShadowDomProps) => JSX.Element;
-
+declare const useShadowDomStylesLoading: (element: Element | null) => boolean;
 /**
  * Props for {@link TechDocsShadowDom}.
  *
@@ -242,7 +246,7 @@ export declare const TechDocsShadowDom: ({ element, onAppend, children, }: TechD
  *
  * @public
  */
-export declare type TechDocsShadowDomProps = PropsWithChildren<{
+declare type TechDocsShadowDomProps = PropsWithChildren<{
     /**
      * Element tree that is appended to ShadowRoot.
      */
@@ -252,60 +256,34 @@ export declare type TechDocsShadowDomProps = PropsWithChildren<{
      */
     onAppend?: (shadowRoot: ShadowRoot) => void;
 }>;
-
 /**
- * API which talks to TechDocs storage to fetch files to render.
- *
- * @public
- */
-export declare interface TechDocsStorageApi {
-    getApiOrigin(): Promise<string>;
-    getStorageUrl(): Promise<string>;
-    getBuilder(): Promise<string>;
-    getEntityDocs(entityId: CompoundEntityRef, path: string): Promise<string>;
-    syncEntityDocs(entityId: CompoundEntityRef, logHandler?: (line: string) => void): Promise<SyncResult>;
-    getBaseUrl(oldBaseUrl: string, entityId: CompoundEntityRef, path: string): Promise<string>;
-}
-
-/**
- * Utility API reference for the {@link TechDocsStorageApi}.
- *
- * @public
- */
-export declare const techdocsStorageApiRef: ApiRef<TechDocsStorageApi>;
-
-/**
- * Lower-case entity triplets by default, but allow override.
+ * Renders a tree of elements in a Shadow DOM.
  *
- * @public
- */
-export declare function toLowercaseEntityRefMaybe(entityRef: CompoundEntityRef, config: Config): CompoundEntityRef;
-
-/**
- * Returns the style's loading state.
+ * @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's an example that updates the sidebar position only after styles are calculated:
- * ```jsx
+ * Here is an example using this component and also listening for styles loaded event:
+ *```jsx
  * import {
  *   TechDocsShadowDom,
- *   useShadowDomStylesLoading,
+ *   SHADOW_DOM_STYLE_LOAD_EVENT,
  * } from '@backstage/plugin-techdocs-react';
  *
- * export const TechDocsReaderPageContent = () => {
+ * export const TechDocsReaderPageContent = ({ entity }: TechDocsReaderPageContentProps) => {
  *   // ...
  *   const dom = useTechDocsReaderDom(entity);
- *   const isStyleLoading = useShadowDomStylesLoading(dom);
- *
- *   const updateSidebarPosition = useCallback(() => {
- *     //...
- *   }, [dom]);
  *
  *   useEffect(() => {
- *     if (!isStyleLoading) {
- *       updateSidebarPosition();
- *     }
- *   }, [isStyleLoading, updateSidebarPosition]);
+ *     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) => {
@@ -318,46 +296,35 @@ export declare function toLowercaseEntityRefMaybe(entityRef: CompoundEntityRef,
  * };
  * ```
  *
- * @param element - which is the ShadowRoot tree.
- * @returns a boolean value, true if styles are being loaded.
+ * @param props - see {@link TechDocsShadowDomProps}.
  * @public
  */
-export declare const useShadowDomStylesLoading: (element: Element | null) => boolean;
+declare const TechDocsShadowDom: ({ element, onAppend, children, }: TechDocsShadowDomProps) => JSX.Element;
 
 /**
  * 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;
-
+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.
  *
  * @public
  */
-export declare const useShadowRootElements: <TReturnedElement extends HTMLElement = HTMLElement>(selectors: string[]) => TReturnedElement[];
-
+declare const useShadowRootElements: <TReturnedElement extends HTMLElement = HTMLElement>(selectors: string[]) => TReturnedElement[];
 /**
  * Hook for retrieving a selection within the ShadowRoot.
  * @public
  */
-export declare const useShadowRootSelection: (waitMillis?: number) => Selection | null;
-
-/**
- * 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;
-};
+declare const useShadowRootSelection: (waitMillis?: number) => Selection | null;
 
 /**
- * Hook used to get access to shared state between reader page components.
+ * Lower-case entity triplets by default, but allow override.
+ *
  * @public
  */
-export declare const useTechDocsReaderPage: () => TechDocsReaderPageValue;
+declare function toLowercaseEntityRefMaybe(entityRef: CompoundEntityRef, config: Config): CompoundEntityRef;
 
-export { }
+export { SHADOW_DOM_STYLE_LOAD_EVENT, SyncResult, TECHDOCS_ADDONS_KEY, TECHDOCS_ADDONS_WRAPPER_KEY, TechDocsAddonLocations, TechDocsAddonOptions, TechDocsAddons, TechDocsApi, TechDocsEntityMetadata, TechDocsMetadata, TechDocsReaderPageProvider, TechDocsReaderPageProviderProps, TechDocsReaderPageProviderRenderFunction, TechDocsReaderPageValue, TechDocsShadowDom, TechDocsShadowDomProps, TechDocsStorageApi, createTechDocsAddonExtension, techdocsApiRef, techdocsStorageApiRef, toLowercaseEntityRefMaybe, useShadowDomStylesLoading, useShadowRoot, useShadowRootElements, useShadowRootSelection, useTechDocsAddons, useTechDocsReaderPage };

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "@backstage/plugin-techdocs-react",
   "description": "Shared frontend utilities for TechDocs and Addons",
-  "version": "1.1.3",
+  "version": "1.1.4-next.1",
   "publishConfig": {
     "access": "public",
-    "alphaTypes": "dist/index.alpha.d.ts",
     "main": "dist/index.esm.js",
     "types": "dist/index.d.ts"
   },
@@ -25,7 +24,7 @@
   "main": "dist/index.esm.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "backstage-cli package build --experimental-type-build",
+    "build": "backstage-cli package build",
     "lint": "backstage-cli package lint",
     "test": "backstage-cli package test",
     "prepack": "backstage-cli package prepack",
@@ -34,15 +33,15 @@
     "start": "backstage-cli package start"
   },
   "dependencies": {
-    "@backstage/catalog-model": "^1.2.0",
-    "@backstage/config": "^1.0.6",
-    "@backstage/core-components": "^0.12.4",
-    "@backstage/core-plugin-api": "^1.4.0",
+    "@backstage/catalog-model": "^1.2.1-next.1",
+    "@backstage/config": "^1.0.7-next.0",
+    "@backstage/core-components": "^0.12.5-next.1",
+    "@backstage/core-plugin-api": "^1.4.1-next.1",
     "@backstage/version-bridge": "^1.0.3",
     "@material-ui/core": "^4.12.2",
     "@material-ui/lab": "4.0.0-alpha.57",
     "@material-ui/styles": "^4.11.0",
-    "jss": "~10.9.0",
+    "jss": "~10.10.0",
     "lodash": "^4.17.21",
     "react-helmet": "6.1.0",
     "react-use": "^17.2.4"
@@ -53,9 +52,9 @@
     "react-router-dom": "6.0.0-beta.0 || ^6.3.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.22.2",
-    "@backstage/test-utils": "^1.2.5",
-    "@backstage/theme": "^0.2.17",
+    "@backstage/cli": "^0.22.4-next.1",
+    "@backstage/test-utils": "^1.2.6-next.1",
+    "@backstage/theme": "^0.2.18-next.0",
     "@testing-library/jest-dom": "^5.10.1",
     "@testing-library/react": "^12.1.3",
     "@testing-library/react-hooks": "^8.0.0"
@@ -63,5 +62,6 @@
   "files": [
     "alpha",
     "dist"
-  ]
+  ],
+  "module": "./dist/index.esm.js"
 }

package/alpha/package.json

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

package/dist/index.alpha.d.ts

@@ -1,363 +0,0 @@
-/**
- * Package encapsulating utilities to be shared by frontend TechDocs plugins.
- *
- * @packageDocumentation
- */
-
-import { ApiRef } from '@backstage/core-plugin-api';
-import { AsyncState } from 'react-use/lib/useAsync';
-import { ComponentType } from 'react';
-import { CompoundEntityRef } from '@backstage/catalog-model';
-import { Config } from '@backstage/config';
-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 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>;
-
-/**
- * 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.
- *
- * @public
- */
-export declare type SyncResult = 'cached' | 'updated';
-
-/**
- * Key for each addon.
- * @public
- */
-export declare const TECHDOCS_ADDONS_KEY = "techdocs.addons.addon.v1";
-
-/**
- * Marks the `<TechDocsAddons>` registry component.
- * @public
- */
-export declare const TECHDOCS_ADDONS_WRAPPER_KEY = "techdocs.addons.wrapper.v1";
-
-/**
- * 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";
-}>;
-
-/**
- * Options for creating a TechDocs addon.
- * @public
- */
-export declare type TechDocsAddonOptions<TAddonProps = {}> = {
-    name: string;
-    location: keyof typeof TechDocsAddonLocations;
-    component: ComponentType<TAddonProps>;
-};
-
-/**
- * TechDocs Addon registry.
- * @public
- */
-export declare const TechDocsAddons: React_2.ComponentType<React_2.PropsWithChildren<{}>>;
-
-/**
- * API to talk to techdocs-backend.
- *
- * @public
- */
-export declare interface TechDocsApi {
-    getApiOrigin(): Promise<string>;
-    getTechDocsMetadata(entityId: CompoundEntityRef): Promise<TechDocsMetadata>;
-    getEntityMetadata(entityId: CompoundEntityRef): Promise<TechDocsEntityMetadata>;
-}
-
-/**
- * Utility API reference for the {@link TechDocsApi}.
- *
- * @public
- */
-export declare const techdocsApiRef: ApiRef<TechDocsApi>;
-
-/**
- * Metadata for TechDocs Entity
- *
- * @public
- */
-export declare type TechDocsEntityMetadata = Entity & {
-    locationMetadata?: {
-        type: string;
-        target: string;
-    };
-};
-
-/**
- * Metadata for TechDocs page
- *
- * @public
- */
-export declare type TechDocsMetadata = {
-    site_name: string;
-    site_description: string;
-};
-
-/**
- * A context to store the reader page state
- * @public
- */
-export declare const TechDocsReaderPageProvider: React_2.MemoExoticComponent<({ entityRef, children }: TechDocsReaderPageProviderProps) => JSX.Element>;
-
-/**
- * Props for {@link TechDocsReaderPageProvider}
- *
- * @public
- */
-export declare type TechDocsReaderPageProviderProps = {
-    entityRef: CompoundEntityRef;
-    children: TechDocsReaderPageProviderRenderFunction | ReactNode;
-};
-
-/**
- * render function for {@link TechDocsReaderPageProvider}
- *
- * @public
- */
-export declare type TechDocsReaderPageProviderRenderFunction = (value: TechDocsReaderPageValue) => JSX.Element;
-
-/**
- * @public type for the value of the TechDocsReaderPageContext
- */
-export declare type TechDocsReaderPageValue = {
-    metadata: AsyncState<TechDocsMetadata>;
-    entityRef: CompoundEntityRef;
-    entityMetadata: AsyncState<TechDocsEntityMetadata>;
-    shadowRoot?: ShadowRoot;
-    setShadowRoot: Dispatch<SetStateAction<ShadowRoot | undefined>>;
-    title: string;
-    setTitle: Dispatch<SetStateAction<string>>;
-    subtitle: string;
-    setSubtitle: Dispatch<SetStateAction<string>>;
-    /**
-     * @deprecated property can be passed down directly to the `TechDocsReaderPageContent` instead.
-     */
-    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.
- *
- * @public
- */
-export declare interface TechDocsStorageApi {
-    getApiOrigin(): Promise<string>;
-    getStorageUrl(): Promise<string>;
-    getBuilder(): Promise<string>;
-    getEntityDocs(entityId: CompoundEntityRef, path: string): Promise<string>;
-    syncEntityDocs(entityId: CompoundEntityRef, logHandler?: (line: string) => void): Promise<SyncResult>;
-    getBaseUrl(oldBaseUrl: string, entityId: CompoundEntityRef, path: string): Promise<string>;
-}
-
-/**
- * Utility API reference for the {@link TechDocsStorageApi}.
- *
- * @public
- */
-export declare const techdocsStorageApiRef: ApiRef<TechDocsStorageApi>;
-
-/**
- * Lower-case entity triplets by default, but allow override.
- *
- * @public
- */
-export declare function toLowercaseEntityRefMaybe(entityRef: CompoundEntityRef, config: Config): CompoundEntityRef;
-
-/**
- * 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;
-
-/**
- * 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[];
-
-/**
- * Hook for retrieving a selection within the ShadowRoot.
- * @public
- */
-export declare const useShadowRootSelection: (waitMillis?: number) => Selection | null;
-
-/**
- * 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;
-};
-
-/**
- * Hook used to get access to shared state between reader page components.
- * @public
- */
-export declare const useTechDocsReaderPage: () => TechDocsReaderPageValue;
-
-export { }

package/dist/index.beta.d.ts

@@ -1,363 +0,0 @@
-/**
- * Package encapsulating utilities to be shared by frontend TechDocs plugins.
- *
- * @packageDocumentation
- */
-
-import { ApiRef } from '@backstage/core-plugin-api';
-import { AsyncState } from 'react-use/lib/useAsync';
-import { ComponentType } from 'react';
-import { CompoundEntityRef } from '@backstage/catalog-model';
-import { Config } from '@backstage/config';
-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 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>;
-
-/**
- * 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.
- *
- * @public
- */
-export declare type SyncResult = 'cached' | 'updated';
-
-/**
- * Key for each addon.
- * @public
- */
-export declare const TECHDOCS_ADDONS_KEY = "techdocs.addons.addon.v1";
-
-/**
- * Marks the `<TechDocsAddons>` registry component.
- * @public
- */
-export declare const TECHDOCS_ADDONS_WRAPPER_KEY = "techdocs.addons.wrapper.v1";
-
-/**
- * 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";
-}>;
-
-/**
- * Options for creating a TechDocs addon.
- * @public
- */
-export declare type TechDocsAddonOptions<TAddonProps = {}> = {
-    name: string;
-    location: keyof typeof TechDocsAddonLocations;
-    component: ComponentType<TAddonProps>;
-};
-
-/**
- * TechDocs Addon registry.
- * @public
- */
-export declare const TechDocsAddons: React_2.ComponentType<React_2.PropsWithChildren<{}>>;
-
-/**
- * API to talk to techdocs-backend.
- *
- * @public
- */
-export declare interface TechDocsApi {
-    getApiOrigin(): Promise<string>;
-    getTechDocsMetadata(entityId: CompoundEntityRef): Promise<TechDocsMetadata>;
-    getEntityMetadata(entityId: CompoundEntityRef): Promise<TechDocsEntityMetadata>;
-}
-
-/**
- * Utility API reference for the {@link TechDocsApi}.
- *
- * @public
- */
-export declare const techdocsApiRef: ApiRef<TechDocsApi>;
-
-/**
- * Metadata for TechDocs Entity
- *
- * @public
- */
-export declare type TechDocsEntityMetadata = Entity & {
-    locationMetadata?: {
-        type: string;
-        target: string;
-    };
-};
-
-/**
- * Metadata for TechDocs page
- *
- * @public
- */
-export declare type TechDocsMetadata = {
-    site_name: string;
-    site_description: string;
-};
-
-/**
- * A context to store the reader page state
- * @public
- */
-export declare const TechDocsReaderPageProvider: React_2.MemoExoticComponent<({ entityRef, children }: TechDocsReaderPageProviderProps) => JSX.Element>;
-
-/**
- * Props for {@link TechDocsReaderPageProvider}
- *
- * @public
- */
-export declare type TechDocsReaderPageProviderProps = {
-    entityRef: CompoundEntityRef;
-    children: TechDocsReaderPageProviderRenderFunction | ReactNode;
-};
-
-/**
- * render function for {@link TechDocsReaderPageProvider}
- *
- * @public
- */
-export declare type TechDocsReaderPageProviderRenderFunction = (value: TechDocsReaderPageValue) => JSX.Element;
-
-/**
- * @public type for the value of the TechDocsReaderPageContext
- */
-export declare type TechDocsReaderPageValue = {
-    metadata: AsyncState<TechDocsMetadata>;
-    entityRef: CompoundEntityRef;
-    entityMetadata: AsyncState<TechDocsEntityMetadata>;
-    shadowRoot?: ShadowRoot;
-    setShadowRoot: Dispatch<SetStateAction<ShadowRoot | undefined>>;
-    title: string;
-    setTitle: Dispatch<SetStateAction<string>>;
-    subtitle: string;
-    setSubtitle: Dispatch<SetStateAction<string>>;
-    /**
-     * @deprecated property can be passed down directly to the `TechDocsReaderPageContent` instead.
-     */
-    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.
- *
- * @public
- */
-export declare interface TechDocsStorageApi {
-    getApiOrigin(): Promise<string>;
-    getStorageUrl(): Promise<string>;
-    getBuilder(): Promise<string>;
-    getEntityDocs(entityId: CompoundEntityRef, path: string): Promise<string>;
-    syncEntityDocs(entityId: CompoundEntityRef, logHandler?: (line: string) => void): Promise<SyncResult>;
-    getBaseUrl(oldBaseUrl: string, entityId: CompoundEntityRef, path: string): Promise<string>;
-}
-
-/**
- * Utility API reference for the {@link TechDocsStorageApi}.
- *
- * @public
- */
-export declare const techdocsStorageApiRef: ApiRef<TechDocsStorageApi>;
-
-/**
- * Lower-case entity triplets by default, but allow override.
- *
- * @public
- */
-export declare function toLowercaseEntityRefMaybe(entityRef: CompoundEntityRef, config: Config): CompoundEntityRef;
-
-/**
- * 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;
-
-/**
- * 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[];
-
-/**
- * Hook for retrieving a selection within the ShadowRoot.
- * @public
- */
-export declare const useShadowRootSelection: (waitMillis?: number) => Selection | null;
-
-/**
- * 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;
-};
-
-/**
- * Hook used to get access to shared state between reader page components.
- * @public
- */
-export declare const useTechDocsReaderPage: () => TechDocsReaderPageValue;
-
-export { }