From f04b458bbc35d6c5fc4ea0f7185a17716a55bee6 Mon Sep 17 00:00:00 2001
From: Eric Peterson <ericpeterson@spotify.com>
Date: Fri, 1 Apr 2022 18:27:43 +0200
Subject: [PATCH] Resolve or clarify simpler todos in techdocs-addons

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>
---
 packages/techdocs-addons/api-report.md        |  1 -
 packages/techdocs-addons/src/types.ts         | 29 ++++++++++++++-----
 .../components/TechDocsReaderPage/hooks.ts    |  5 ----
 3 files changed, 22 insertions(+), 13 deletions(-)

diff --git a/packages/techdocs-addons/api-report.md b/packages/techdocs-addons/api-report.md
index 0afcb9f3a3..4d5eef5edb 100644
--- a/packages/techdocs-addons/api-report.md
+++ b/packages/techdocs-addons/api-report.md
@@ -21,7 +21,6 @@ export type TechDocsAddonAsyncMetadata<TValue> = AsyncState<TValue | undefined>;
 
 // @public
 export enum TechDocsAddonLocations {
-  COMPONENT = 'component',
   CONTENT = 'content',
   HEADER = 'header',
   PRIMARY_SIDEBAR = 'primary sidebar',
diff --git a/packages/techdocs-addons/src/types.ts b/packages/techdocs-addons/src/types.ts
index 8e42e0a6bc..aa0d128427 100644
--- a/packages/techdocs-addons/src/types.ts
+++ b/packages/techdocs-addons/src/types.ts
@@ -51,15 +51,30 @@ export enum TechDocsAddonLocations {
   CONTENT = 'content',
 
   /**
-   * A virtual location allowing an instance of the addon to be rendered for
-   * every HTML node with the same tag name as the addon name in the markdown
-   * content. If no reference is made, no instance will be rendered. Works like
-   * regular React components, just being accessible from markdown.
+   * todo(backstage/community): This is a proposed virtual location which would
+   * help implement a common addon pattern in which many instances of a given
+   * element in markdown would be dynamically replaced at render-time based on
+   * attributes provided on that element, for example:
    *
-   * todo(backstage/techdocs-core): Keep and implement or remove before
-   * releasing this package!
+   * ```md
+   * ## Component Metadata
+   * [CatalogEntityCard](default:component/some-component-name)
+   *
+   * ## System Metadata
+   * [CatalogEntityCard](default:system/some-system-name)
+   * ```
+   *
+   * Could correspond to a TechDocs addon named `CatalogEntityCard` with
+   * location `TechDocsAddonLocations.COMPONENT`, whose `component` would be
+   * the react component that would be rendered in place of all instances of
+   * the markdown illustrated above.
+   *
+   * The `@backstage/techdocs-addons` plugin would need to be updated to, in
+   * cases where such addons had been registered, find all instances of the
+   * rendered markdown (e.g. `<a href="{entityRef}">CatalogEntityCard</a>`) and
+   * replace them with react portals to the addon component.
    */
-  COMPONENT = 'component',
+  // COMPONENT = 'component',
 }
 
 /**
diff --git a/plugins/techdocs/src/reader/components/TechDocsReaderPage/hooks.ts b/plugins/techdocs/src/reader/components/TechDocsReaderPage/hooks.ts
index 7bc6152006..ac81a56132 100644
--- a/plugins/techdocs/src/reader/components/TechDocsReaderPage/hooks.ts
+++ b/plugins/techdocs/src/reader/components/TechDocsReaderPage/hooks.ts
@@ -29,11 +29,6 @@ export const useShadowRoot = () => {
  * Convenience hook for use within TechDocs addons that provides access to
  * elements that match a given selector within the shadow root.
  *
- * todo(backstage/techdocs-core): Consider extending `selectors` from string[]
- * to some kind of typed object array, so users have more control over the
- * shape of the result. e.g. a flag to indicate querySelector vs.
- * querySelectorAll.
- *
  * @public
  */
 export const useShadowRootElements = <