@backstage/frontend-plugin-api 0.12.2-next.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @backstage/frontend-plugin-api
 
+## 0.13.0
+
+### Minor Changes
+
+- 7d87b4f: Renamed `ExtensionDefinition` to `OverridableExtensionDefinition` and introduced a slimmer `ExtensionDefinition` type that does not include override methods. The overridable type is generally used as an output type, while plain `ExtensionDefinition`s are used for input. This reduces type conflicts across different of `@backstage/frontend-plugin-api`, improving long-term compatibility.
+
+### Patch Changes
+
+- 4d03f08: Internal refactor of route reference implementations with minor updates to the `toString` implementations.
+- 7c6a66d: Added support for plugin-relative `attachTo` declarations for extension definitions. This allows for the creation of extension and extension blueprints that attach to other extensions of a particular `kind` in the same plugin, rather than needing to provide the exact extension ID. This is particularly useful when wanting to provide extension blueprints with a built-in hierarchy where the extensions created from one blueprint attach to extensions created from the other blueprint, for example:
+
+  ```ts
+  // kind: 'tabbed-page'
+  const parentPage = TabbedPageBlueprint.make({
+    params: {....}
+  })
+  // attachTo: { kind: 'tabbed-page', input: 'tabs' }
+  const child1 = TabContentBlueprint.make({
+    name: 'tab1',
+    params: {....}
+  })
+  ```
+
+- 878c251: Updated to `ExtensionInput` to make all type parameters optional.
+- 05f60e1: Refactored constructor parameter properties to explicit property declarations for compatibility with TypeScript's `erasableSyntaxOnly` setting. This internal refactoring maintains all existing functionality while ensuring TypeScript compilation compatibility.
+- Updated dependencies
+  - @backstage/core-components@0.18.3
+  - @backstage/core-plugin-api@1.12.0
+
+## 0.12.2-next.2
+
+### Patch Changes
+
+- 7c6a66d: Added support for plugin-relative `attachTo` declarations for extension definitions. This allows for the creation of extension and extension blueprints that attach to other extensions of a particular `kind` in the same plugin, rather than needing to provide the exact extension ID. This is particularly useful when wanting to provide extension blueprints with a built-in hierarchy where the extensions created from one blueprint attach to extensions created from the other blueprint, for example:
+
+  ```ts
+  // kind: 'tabbed-page'
+  const parentPage = TabbedPageBlueprint.make({
+    params: {....}
+  })
+  // attachTo: { kind: 'tabbed-page', input: 'tabs' }
+  const child1 = TabContentBlueprint.make({
+    name: 'tab1',
+    params: {....}
+  })
+  ```
+
+- Updated dependencies
+  - @backstage/core-components@0.18.3-next.2
+
 ## 0.12.2-next.1
 
 ### Patch Changes

package/dist/apis/definitions/AppTreeApi.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"AppTreeApi.esm.js","sources":["../../../src/apis/definitions/AppTreeApi.ts"],"sourcesContent":["/*\n * Copyright 2023 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 { createApiRef } from '@backstage/core-plugin-api';\nimport {\n  FrontendPlugin,\n  Extension,\n  ExtensionDataRef,\n  ExtensionAttachToSpec,\n} from '../../wiring';\n\n/**\n * The specification for this {@link AppNode} in the {@link AppTree}.\n *\n * @public\n * @remarks\n *\n * The specifications for a collection of app nodes is all the information needed\n * to build the tree and instantiate the nodes.\n */\nexport interface AppNodeSpec {\n  readonly id: string;\n  readonly attachTo: ExtensionAttachToSpec;\n  readonly extension: Extension<unknown, unknown>;\n  readonly disabled: boolean;\n  readonly config?: unknown;\n  readonly plugin: FrontendPlugin;\n}\n\n/**\n * The connections from this {@link AppNode} to other nodes.\n *\n * @public\n * @remarks\n *\n * The app node edges are resolved based on the app node specs, regardless of whether\n * adjacent nodes are disabled or not. If no parent attachment is present or\n */\nexport interface AppNodeEdges {\n  readonly attachedTo?: { node: AppNode; input: string };\n  readonly attachments: ReadonlyMap<string, AppNode[]>;\n}\n\n/**\n * The instance of this {@link AppNode} in the {@link AppTree}.\n *\n * @public\n * @remarks\n *\n * The app node instance is created when the `factory` function of an extension is called.\n * Instances will only be present for nodes in the app that are connected to the root\n * node and not disabled\n */\nexport interface AppNodeInstance {\n  /** Returns a sequence of all extension data refs that were output by this instance */\n  getDataRefs(): Iterable<ExtensionDataRef<unknown>>;\n  /** Get the output data for a single extension data ref */\n  getData<T>(ref: ExtensionDataRef<T>): T | undefined;\n}\n\n/**\n * A node in the {@link AppTree}.\n *\n * @public\n */\nexport interface AppNode {\n  /** The specification for how this node should be instantiated */\n  readonly spec: AppNodeSpec;\n  /** The edges from this node to other nodes in the app tree */\n  readonly edges: AppNodeEdges;\n  /** The instance of this node, if it was instantiated */\n  readonly instance?: AppNodeInstance;\n}\n\n/**\n * The app tree containing all {@link AppNode}s of the app.\n *\n * @public\n */\nexport interface AppTree {\n  /** The root node of the app */\n  readonly root: AppNode;\n  /** A map of all nodes in the app by ID, including orphaned or disabled nodes */\n  readonly nodes: ReadonlyMap<string /* id */, AppNode>;\n  /** A sequence of all nodes with a parent that is not reachable from the app root node */\n  readonly orphans: Iterable<AppNode>;\n}\n\n/**\n * The API for interacting with the {@link AppTree}.\n *\n * @public\n */\nexport interface AppTreeApi {\n  /**\n   * Get the {@link AppTree} for the app.\n   */\n  getTree(): { tree: AppTree };\n\n  /**\n   * Get all nodes in the app that are mounted at a given route path.\n   */\n  getNodesByRoutePath(routePath: string): { nodes: AppNode[] };\n}\n\n/**\n * The `ApiRef` of {@link AppTreeApi}.\n *\n * @public\n */\nexport const appTreeApiRef = createApiRef<AppTreeApi>({ id: 'core.app-tree' });\n"],"names":[],"mappings":";;AA2HO,MAAM,aAAA,GAAgB,YAAA,CAAyB,EAAE,EAAA,EAAI,iBAAiB;;;;"}
+{"version":3,"file":"AppTreeApi.esm.js","sources":["../../../src/apis/definitions/AppTreeApi.ts"],"sourcesContent":["/*\n * Copyright 2023 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 { createApiRef } from '@backstage/core-plugin-api';\nimport { FrontendPlugin, Extension, ExtensionDataRef } from '../../wiring';\nimport { ExtensionAttachTo } from '../../wiring/resolveExtensionDefinition';\n\n/**\n * The specification for this {@link AppNode} in the {@link AppTree}.\n *\n * @public\n * @remarks\n *\n * The specifications for a collection of app nodes is all the information needed\n * to build the tree and instantiate the nodes.\n */\nexport interface AppNodeSpec {\n  readonly id: string;\n  readonly attachTo: ExtensionAttachTo;\n  readonly extension: Extension<unknown, unknown>;\n  readonly disabled: boolean;\n  readonly config?: unknown;\n  readonly plugin: FrontendPlugin;\n}\n\n/**\n * The connections from this {@link AppNode} to other nodes.\n *\n * @public\n * @remarks\n *\n * The app node edges are resolved based on the app node specs, regardless of whether\n * adjacent nodes are disabled or not. If no parent attachment is present or\n */\nexport interface AppNodeEdges {\n  readonly attachedTo?: { node: AppNode; input: string };\n  readonly attachments: ReadonlyMap<string, AppNode[]>;\n}\n\n/**\n * The instance of this {@link AppNode} in the {@link AppTree}.\n *\n * @public\n * @remarks\n *\n * The app node instance is created when the `factory` function of an extension is called.\n * Instances will only be present for nodes in the app that are connected to the root\n * node and not disabled\n */\nexport interface AppNodeInstance {\n  /** Returns a sequence of all extension data refs that were output by this instance */\n  getDataRefs(): Iterable<ExtensionDataRef<unknown>>;\n  /** Get the output data for a single extension data ref */\n  getData<T>(ref: ExtensionDataRef<T>): T | undefined;\n}\n\n/**\n * A node in the {@link AppTree}.\n *\n * @public\n */\nexport interface AppNode {\n  /** The specification for how this node should be instantiated */\n  readonly spec: AppNodeSpec;\n  /** The edges from this node to other nodes in the app tree */\n  readonly edges: AppNodeEdges;\n  /** The instance of this node, if it was instantiated */\n  readonly instance?: AppNodeInstance;\n}\n\n/**\n * The app tree containing all {@link AppNode}s of the app.\n *\n * @public\n */\nexport interface AppTree {\n  /** The root node of the app */\n  readonly root: AppNode;\n  /** A map of all nodes in the app by ID, including orphaned or disabled nodes */\n  readonly nodes: ReadonlyMap<string /* id */, AppNode>;\n  /** A sequence of all nodes with a parent that is not reachable from the app root node */\n  readonly orphans: Iterable<AppNode>;\n}\n\n/**\n * The API for interacting with the {@link AppTree}.\n *\n * @public\n */\nexport interface AppTreeApi {\n  /**\n   * Get the {@link AppTree} for the app.\n   */\n  getTree(): { tree: AppTree };\n\n  /**\n   * Get all nodes in the app that are mounted at a given route path.\n   */\n  getNodesByRoutePath(routePath: string): { nodes: AppNode[] };\n}\n\n/**\n * The `ApiRef` of {@link AppTreeApi}.\n *\n * @public\n */\nexport const appTreeApiRef = createApiRef<AppTreeApi>({ id: 'core.app-tree' });\n"],"names":[],"mappings":";;AAuHO,MAAM,aAAA,GAAgB,YAAA,CAAyB,EAAE,EAAA,EAAI,iBAAiB;;;;"}

package/dist/components/createSwappableComponent.esm.js

@@ -9,6 +9,7 @@ import '../apis/definitions/AnalyticsApi.esm.js';
 import { lazy } from 'react';
 import { OpaqueSwappableComponentRef } from '../frontend-internal/src/wiring/InternalSwappableComponentRef.esm.js';
 import '../frontend-internal/src/wiring/InternalExtensionDefinition.esm.js';
+import '../frontend-internal/src/wiring/InternalExtensionInput.esm.js';
 import '../frontend-internal/src/wiring/InternalFrontendPlugin.esm.js';
 
 const useComponentRefApi = () => {

package/dist/components/createSwappableComponent.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"createSwappableComponent.esm.js","sources":["../../src/components/createSwappableComponent.tsx"],"sourcesContent":["/*\n * Copyright 2023 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 { OpaqueSwappableComponentRef } from '@internal/frontend';\nimport { swappableComponentsApiRef, useApi } from '../apis';\nimport { lazy } from 'react';\n\n/** @public */\nexport type SwappableComponentRef<\n  TInnerComponentProps extends {} = {},\n  TExternalComponentProps extends {} = TInnerComponentProps,\n> = {\n  id: string;\n  TProps: TInnerComponentProps;\n  TExternalProps: TExternalComponentProps;\n  $$type: '@backstage/SwappableComponentRef';\n};\n\n/**\n * Options for creating an SwappableComponent.\n *\n * @public\n */\nexport type CreateSwappableComponentOptions<\n  TInnerComponentProps extends {},\n  TExternalComponentProps extends {} = TInnerComponentProps,\n> = {\n  id: string;\n  loader?:\n    | (() => (props: TInnerComponentProps) => JSX.Element | null)\n    | (() => Promise<(props: TInnerComponentProps) => JSX.Element | null>);\n  transformProps?: (props: TExternalComponentProps) => TInnerComponentProps;\n};\n\nconst useComponentRefApi = () => {\n  try {\n    return useApi(swappableComponentsApiRef);\n  } catch (e) {\n    return undefined;\n  }\n};\n\n/**\n * Creates a SwappableComponent that can be used to render the component, optionally overridden by the app.\n *\n * @public\n */\nexport function createSwappableComponent<\n  TInnerComponentProps extends {},\n  TExternalComponentProps extends {} = TInnerComponentProps,\n>(\n  options: CreateSwappableComponentOptions<\n    TInnerComponentProps,\n    TExternalComponentProps\n  >,\n): {\n  (props: TExternalComponentProps): JSX.Element | null;\n  ref: SwappableComponentRef<TInnerComponentProps, TExternalComponentProps>;\n} {\n  const FallbackComponent = (p: JSX.IntrinsicAttributes) => (\n    <div data-testid={options.id} {...p} />\n  );\n\n  const ref = OpaqueSwappableComponentRef.createInstance('v1', {\n    id: options.id,\n    TProps: null as unknown as TInnerComponentProps,\n    TExternalProps: null as unknown as TExternalComponentProps,\n    toString() {\n      return `SwappableComponentRef{id=${options.id}}`;\n    },\n    defaultComponent: lazy(async () => {\n      const Component = (await options.loader?.()) ?? FallbackComponent;\n      return { default: Component };\n    }) as (typeof OpaqueSwappableComponentRef.TInternal)['defaultComponent'],\n    transformProps:\n      options.transformProps as (typeof OpaqueSwappableComponentRef.TInternal)['transformProps'],\n  });\n\n  const ComponentRefImpl = (props: TExternalComponentProps) => {\n    const api = useComponentRefApi();\n\n    if (!api) {\n      const internalRef = OpaqueSwappableComponentRef.toInternal(ref);\n      const Component = internalRef.defaultComponent;\n      const innerProps = internalRef.transformProps?.(props) ?? props;\n      return <Component {...innerProps} />;\n    }\n\n    const Component = api.getComponent<any>(ref);\n    return <Component {...props} />;\n  };\n\n  Object.assign(ComponentRefImpl, { ref });\n\n  return ComponentRefImpl as {\n    (props: TExternalComponentProps): JSX.Element | null;\n    ref: SwappableComponentRef<TInnerComponentProps, TExternalComponentProps>;\n  };\n}\n"],"names":["Component"],"mappings":";;;;;;;;;;;;;AA+CA,MAAM,qBAAqB,MAAM;AAC/B,EAAA,IAAI;AACF,IAAA,OAAO,OAAO,yBAAyB,CAAA;AAAA,EACzC,SAAS,CAAA,EAAG;AACV,IAAA,OAAO,MAAA;AAAA,EACT;AACF,CAAA;AAOO,SAAS,yBAId,OAAA,EAOA;AACA,EAAA,MAAM,iBAAA,GAAoB,CAAC,CAAA,qBACzB,GAAA,CAAC,SAAI,aAAA,EAAa,OAAA,CAAQ,EAAA,EAAK,GAAG,CAAA,EAAG,CAAA;AAGvC,EAAA,MAAM,GAAA,GAAM,2BAAA,CAA4B,cAAA,CAAe,IAAA,EAAM;AAAA,IAC3D,IAAI,OAAA,CAAQ,EAAA;AAAA,IACZ,MAAA,EAAQ,IAAA;AAAA,IACR,cAAA,EAAgB,IAAA;AAAA,IAChB,QAAA,GAAW;AACT,MAAA,OAAO,CAAA,yBAAA,EAA4B,QAAQ,EAAE,CAAA,CAAA,CAAA;AAAA,IAC/C,CAAA;AAAA,IACA,gBAAA,EAAkB,KAAK,YAAY;AACjC,MAAA,MAAM,SAAA,GAAa,MAAM,OAAA,CAAQ,MAAA,IAAS,IAAM,iBAAA;AAChD,MAAA,OAAO,EAAE,SAAS,SAAA,EAAU;AAAA,IAC9B,CAAC,CAAA;AAAA,IACD,gBACE,OAAA,CAAQ;AAAA,GACX,CAAA;AAED,EAAA,MAAM,gBAAA,GAAmB,CAAC,KAAA,KAAmC;AAC3D,IAAA,MAAM,MAAM,kBAAA,EAAmB;AAE/B,IAAA,IAAI,CAAC,GAAA,EAAK;AACR,MAAA,MAAM,WAAA,GAAc,2BAAA,CAA4B,UAAA,CAAW,GAAG,CAAA;AAC9D,MAAA,MAAMA,aAAY,WAAA,CAAY,gBAAA;AAC9B,MAAA,MAAM,UAAA,GAAa,WAAA,CAAY,cAAA,GAAiB,KAAK,CAAA,IAAK,KAAA;AAC1D,MAAA,uBAAO,GAAA,CAACA,UAAAA,EAAA,EAAW,GAAG,UAAA,EAAY,CAAA;AAAA,IACpC;AAEA,IAAA,MAAM,SAAA,GAAY,GAAA,CAAI,YAAA,CAAkB,GAAG,CAAA;AAC3C,IAAA,uBAAO,GAAA,CAAC,SAAA,EAAA,EAAW,GAAG,KAAA,EAAO,CAAA;AAAA,EAC/B,CAAA;AAEA,EAAA,MAAA,CAAO,MAAA,CAAO,gBAAA,EAAkB,EAAE,GAAA,EAAK,CAAA;AAEvC,EAAA,OAAO,gBAAA;AAIT;;;;"}
+{"version":3,"file":"createSwappableComponent.esm.js","sources":["../../src/components/createSwappableComponent.tsx"],"sourcesContent":["/*\n * Copyright 2023 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 { OpaqueSwappableComponentRef } from '@internal/frontend';\nimport { swappableComponentsApiRef, useApi } from '../apis';\nimport { lazy } from 'react';\n\n/** @public */\nexport type SwappableComponentRef<\n  TInnerComponentProps extends {} = {},\n  TExternalComponentProps extends {} = TInnerComponentProps,\n> = {\n  id: string;\n  TProps: TInnerComponentProps;\n  TExternalProps: TExternalComponentProps;\n  $$type: '@backstage/SwappableComponentRef';\n};\n\n/**\n * Options for creating an SwappableComponent.\n *\n * @public\n */\nexport type CreateSwappableComponentOptions<\n  TInnerComponentProps extends {},\n  TExternalComponentProps extends {} = TInnerComponentProps,\n> = {\n  id: string;\n  loader?:\n    | (() => (props: TInnerComponentProps) => JSX.Element | null)\n    | (() => Promise<(props: TInnerComponentProps) => JSX.Element | null>);\n  transformProps?: (props: TExternalComponentProps) => TInnerComponentProps;\n};\n\nconst useComponentRefApi = () => {\n  try {\n    return useApi(swappableComponentsApiRef);\n  } catch (e) {\n    return undefined;\n  }\n};\n\n/**\n * Creates a SwappableComponent that can be used to render the component, optionally overridden by the app.\n *\n * @public\n */\nexport function createSwappableComponent<\n  TInnerComponentProps extends {},\n  TExternalComponentProps extends {} = TInnerComponentProps,\n>(\n  options: CreateSwappableComponentOptions<\n    TInnerComponentProps,\n    TExternalComponentProps\n  >,\n): {\n  (props: TExternalComponentProps): JSX.Element | null;\n  ref: SwappableComponentRef<TInnerComponentProps, TExternalComponentProps>;\n} {\n  const FallbackComponent = (p: JSX.IntrinsicAttributes) => (\n    <div data-testid={options.id} {...p} />\n  );\n\n  const ref = OpaqueSwappableComponentRef.createInstance('v1', {\n    id: options.id,\n    TProps: null as unknown as TInnerComponentProps,\n    TExternalProps: null as unknown as TExternalComponentProps,\n    toString() {\n      return `SwappableComponentRef{id=${options.id}}`;\n    },\n    defaultComponent: lazy(async () => {\n      const Component = (await options.loader?.()) ?? FallbackComponent;\n      return { default: Component };\n    }) as (typeof OpaqueSwappableComponentRef.TInternal)['defaultComponent'],\n    transformProps:\n      options.transformProps as (typeof OpaqueSwappableComponentRef.TInternal)['transformProps'],\n  });\n\n  const ComponentRefImpl = (props: TExternalComponentProps) => {\n    const api = useComponentRefApi();\n\n    if (!api) {\n      const internalRef = OpaqueSwappableComponentRef.toInternal(ref);\n      const Component = internalRef.defaultComponent;\n      const innerProps = internalRef.transformProps?.(props) ?? props;\n      return <Component {...innerProps} />;\n    }\n\n    const Component = api.getComponent<any>(ref);\n    return <Component {...props} />;\n  };\n\n  Object.assign(ComponentRefImpl, { ref });\n\n  return ComponentRefImpl as {\n    (props: TExternalComponentProps): JSX.Element | null;\n    ref: SwappableComponentRef<TInnerComponentProps, TExternalComponentProps>;\n  };\n}\n"],"names":["Component"],"mappings":";;;;;;;;;;;;;;AA+CA,MAAM,qBAAqB,MAAM;AAC/B,EAAA,IAAI;AACF,IAAA,OAAO,OAAO,yBAAyB,CAAA;AAAA,EACzC,SAAS,CAAA,EAAG;AACV,IAAA,OAAO,MAAA;AAAA,EACT;AACF,CAAA;AAOO,SAAS,yBAId,OAAA,EAOA;AACA,EAAA,MAAM,iBAAA,GAAoB,CAAC,CAAA,qBACzB,GAAA,CAAC,SAAI,aAAA,EAAa,OAAA,CAAQ,EAAA,EAAK,GAAG,CAAA,EAAG,CAAA;AAGvC,EAAA,MAAM,GAAA,GAAM,2BAAA,CAA4B,cAAA,CAAe,IAAA,EAAM;AAAA,IAC3D,IAAI,OAAA,CAAQ,EAAA;AAAA,IACZ,MAAA,EAAQ,IAAA;AAAA,IACR,cAAA,EAAgB,IAAA;AAAA,IAChB,QAAA,GAAW;AACT,MAAA,OAAO,CAAA,yBAAA,EAA4B,QAAQ,EAAE,CAAA,CAAA,CAAA;AAAA,IAC/C,CAAA;AAAA,IACA,gBAAA,EAAkB,KAAK,YAAY;AACjC,MAAA,MAAM,SAAA,GAAa,MAAM,OAAA,CAAQ,MAAA,IAAS,IAAM,iBAAA;AAChD,MAAA,OAAO,EAAE,SAAS,SAAA,EAAU;AAAA,IAC9B,CAAC,CAAA;AAAA,IACD,gBACE,OAAA,CAAQ;AAAA,GACX,CAAA;AAED,EAAA,MAAM,gBAAA,GAAmB,CAAC,KAAA,KAAmC;AAC3D,IAAA,MAAM,MAAM,kBAAA,EAAmB;AAE/B,IAAA,IAAI,CAAC,GAAA,EAAK;AACR,MAAA,MAAM,WAAA,GAAc,2BAAA,CAA4B,UAAA,CAAW,GAAG,CAAA;AAC9D,MAAA,MAAMA,aAAY,WAAA,CAAY,gBAAA;AAC9B,MAAA,MAAM,UAAA,GAAa,WAAA,CAAY,cAAA,GAAiB,KAAK,CAAA,IAAK,KAAA;AAC1D,MAAA,uBAAO,GAAA,CAACA,UAAAA,EAAA,EAAW,GAAG,UAAA,EAAY,CAAA;AAAA,IACpC;AAEA,IAAA,MAAM,SAAA,GAAY,GAAA,CAAI,YAAA,CAAkB,GAAG,CAAA;AAC3C,IAAA,uBAAO,GAAA,CAAC,SAAA,EAAA,EAAW,GAAG,KAAA,EAAO,CAAA;AAAA,EAC/B,CAAA;AAEA,EAAA,MAAA,CAAO,MAAA,CAAO,gBAAA,EAAkB,EAAE,GAAA,EAAK,CAAA;AAEvC,EAAA,OAAO,gBAAA;AAIT;;;;"}

package/dist/frontend-internal/src/routing/OpaqueExternalRouteRef.esm.js

@@ -0,0 +1,9 @@
+import { OpaqueType } from '../../../opaque-internal/src/OpaqueType.esm.js';
+
+const OpaqueExternalRouteRef = OpaqueType.create({
+  type: "@backstage/ExternalRouteRef",
+  versions: ["v1"]
+});
+
+export { OpaqueExternalRouteRef };
+//# sourceMappingURL=OpaqueExternalRouteRef.esm.js.map

package/dist/frontend-internal/src/routing/OpaqueExternalRouteRef.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpaqueExternalRouteRef.esm.js","sources":["../../../../../frontend-internal/src/routing/OpaqueExternalRouteRef.ts"],"sourcesContent":["/*\n * Copyright 2025 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 { ExternalRouteRef } from '@backstage/frontend-plugin-api';\nimport { OpaqueType } from '@internal/opaque';\n\nexport const OpaqueExternalRouteRef = OpaqueType.create<{\n  public: ExternalRouteRef;\n  versions: {\n    readonly version: 'v1';\n\n    getParams(): string[];\n    getDescription(): string;\n    getDefaultTarget(): string | undefined;\n\n    setId(id: string): void;\n  };\n}>({\n  type: '@backstage/ExternalRouteRef',\n  versions: ['v1'],\n});\n"],"names":[],"mappings":";;AAmBO,MAAM,sBAAA,GAAyB,WAAW,MAAA,CAW9C;AAAA,EACD,IAAA,EAAM,6BAAA;AAAA,EACN,QAAA,EAAU,CAAC,IAAI;AACjB,CAAC;;;;"}

package/dist/frontend-internal/src/routing/OpaqueRouteRef.esm.js

@@ -0,0 +1,9 @@
+import { OpaqueType } from '../../../opaque-internal/src/OpaqueType.esm.js';
+
+const OpaqueRouteRef = OpaqueType.create({
+  type: "@backstage/RouteRef",
+  versions: ["v1"]
+});
+
+export { OpaqueRouteRef };
+//# sourceMappingURL=OpaqueRouteRef.esm.js.map

package/dist/frontend-internal/src/routing/OpaqueRouteRef.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpaqueRouteRef.esm.js","sources":["../../../../../frontend-internal/src/routing/OpaqueRouteRef.ts"],"sourcesContent":["/*\n * Copyright 2025 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 { RouteRef } from '@backstage/frontend-plugin-api';\nimport { OpaqueType } from '@internal/opaque';\n\nexport const OpaqueRouteRef = OpaqueType.create<{\n  public: RouteRef;\n  versions: {\n    readonly version: 'v1';\n\n    getParams(): string[];\n    getDescription(): string;\n\n    alias: string | undefined;\n\n    setId(id: string): void;\n  };\n}>({\n  type: '@backstage/RouteRef',\n  versions: ['v1'],\n});\n"],"names":[],"mappings":";;AAmBO,MAAM,cAAA,GAAiB,WAAW,MAAA,CAYtC;AAAA,EACD,IAAA,EAAM,qBAAA;AAAA,EACN,QAAA,EAAU,CAAC,IAAI;AACjB,CAAC;;;;"}

package/dist/frontend-internal/src/routing/OpaqueSubRouteRef.esm.js

@@ -0,0 +1,9 @@
+import { OpaqueType } from '../../../opaque-internal/src/OpaqueType.esm.js';
+
+const OpaqueSubRouteRef = OpaqueType.create({
+  type: "@backstage/SubRouteRef",
+  versions: ["v1"]
+});
+
+export { OpaqueSubRouteRef };
+//# sourceMappingURL=OpaqueSubRouteRef.esm.js.map

package/dist/frontend-internal/src/routing/OpaqueSubRouteRef.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpaqueSubRouteRef.esm.js","sources":["../../../../../frontend-internal/src/routing/OpaqueSubRouteRef.ts"],"sourcesContent":["/*\n * Copyright 2025 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 { RouteRef, SubRouteRef } from '@backstage/frontend-plugin-api';\nimport { OpaqueType } from '@internal/opaque';\n\nexport const OpaqueSubRouteRef = OpaqueType.create<{\n  public: SubRouteRef;\n  versions: {\n    readonly version: 'v1';\n\n    getParams(): string[];\n    getParent(): RouteRef;\n    getDescription(): string;\n  };\n}>({\n  type: '@backstage/SubRouteRef',\n  versions: ['v1'],\n});\n"],"names":[],"mappings":";;AAmBO,MAAM,iBAAA,GAAoB,WAAW,MAAA,CASzC;AAAA,EACD,IAAA,EAAM,wBAAA;AAAA,EACN,QAAA,EAAU,CAAC,IAAI;AACjB,CAAC;;;;"}

package/dist/frontend-internal/src/wiring/InternalExtensionDefinition.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"InternalExtensionDefinition.esm.js","sources":["../../../../../frontend-internal/src/wiring/InternalExtensionDefinition.ts"],"sourcesContent":["/*\n * Copyright 2024 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 {\n  ApiHolder,\n  AppNode,\n  ExtensionAttachToSpec,\n  ExtensionDataValue,\n  ExtensionDataRef,\n  ExtensionDefinition,\n  ExtensionDefinitionParameters,\n  ExtensionInput,\n  PortableSchema,\n  ResolvedExtensionInputs,\n} from '@backstage/frontend-plugin-api';\nimport { OpaqueType } from '@internal/opaque';\n\nexport const OpaqueExtensionDefinition = OpaqueType.create<{\n  public: ExtensionDefinition<ExtensionDefinitionParameters>;\n  versions:\n    | {\n        readonly version: 'v1';\n        readonly kind?: string;\n        readonly namespace?: string;\n        readonly name?: string;\n        readonly attachTo: ExtensionAttachToSpec;\n        readonly disabled: boolean;\n        readonly configSchema?: PortableSchema<any, any>;\n        readonly inputs: {\n          [inputName in string]: {\n            $$type: '@backstage/ExtensionInput';\n            extensionData: {\n              [name in string]: ExtensionDataRef;\n            };\n            config: { optional: boolean; singleton: boolean };\n          };\n        };\n        readonly output: {\n          [name in string]: ExtensionDataRef;\n        };\n        factory(context: {\n          node: AppNode;\n          apis: ApiHolder;\n          config: object;\n          inputs: {\n            [inputName in string]: unknown;\n          };\n        }): {\n          [inputName in string]: unknown;\n        };\n      }\n    | {\n        readonly version: 'v2';\n        readonly kind?: string;\n        readonly namespace?: string;\n        readonly name?: string;\n        readonly attachTo: ExtensionAttachToSpec;\n        readonly disabled: boolean;\n        readonly configSchema?: PortableSchema<any, any>;\n        readonly inputs: { [inputName in string]: ExtensionInput };\n        readonly output: Array<ExtensionDataRef>;\n        factory(context: {\n          node: AppNode;\n          apis: ApiHolder;\n          config: object;\n          inputs: ResolvedExtensionInputs<{\n            [inputName in string]: ExtensionInput;\n          }>;\n        }): Iterable<ExtensionDataValue<any, any>>;\n      };\n}>({\n  type: '@backstage/ExtensionDefinition',\n  versions: ['v1', 'v2'],\n});\n"],"names":[],"mappings":";;AA8BO,MAAM,yBAAA,GAA4B,WAAW,MAAA,CAqDjD;AAAA,EACD,IAAA,EAAM,gCAAA;AAAA,EACN,QAAA,EAAU,CAAC,IAAA,EAAM,IAAI;AACvB,CAAC;;;;"}
+{"version":3,"file":"InternalExtensionDefinition.esm.js","sources":["../../../../../frontend-internal/src/wiring/InternalExtensionDefinition.ts"],"sourcesContent":["/*\n * Copyright 2024 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 {\n  ApiHolder,\n  AppNode,\n  ExtensionDefinitionAttachTo,\n  ExtensionDataValue,\n  ExtensionDataRef,\n  OverridableExtensionDefinition,\n  ExtensionDefinitionParameters,\n  ExtensionInput,\n  PortableSchema,\n  ResolvedExtensionInputs,\n} from '@backstage/frontend-plugin-api';\nimport { OpaqueType } from '@internal/opaque';\n\nexport const OpaqueExtensionDefinition = OpaqueType.create<{\n  public: OverridableExtensionDefinition<ExtensionDefinitionParameters>;\n  versions:\n    | {\n        readonly version: 'v1';\n        readonly kind?: string;\n        readonly namespace?: string;\n        readonly name?: string;\n        readonly attachTo: ExtensionDefinitionAttachTo;\n        readonly disabled: boolean;\n        readonly configSchema?: PortableSchema<any, any>;\n        readonly inputs: {\n          [inputName in string]: {\n            $$type: '@backstage/ExtensionInput';\n            extensionData: {\n              [name in string]: ExtensionDataRef;\n            };\n            config: { optional: boolean; singleton: boolean };\n          };\n        };\n        readonly output: {\n          [name in string]: ExtensionDataRef;\n        };\n        factory(context: {\n          node: AppNode;\n          apis: ApiHolder;\n          config: object;\n          inputs: {\n            [inputName in string]: unknown;\n          };\n        }): {\n          [inputName in string]: unknown;\n        };\n      }\n    | {\n        readonly version: 'v2';\n        readonly kind?: string;\n        readonly namespace?: string;\n        readonly name?: string;\n        readonly attachTo: ExtensionDefinitionAttachTo;\n        readonly disabled: boolean;\n        readonly configSchema?: PortableSchema<any, any>;\n        readonly inputs: { [inputName in string]: ExtensionInput };\n        readonly output: Array<ExtensionDataRef>;\n        factory(context: {\n          node: AppNode;\n          apis: ApiHolder;\n          config: object;\n          inputs: ResolvedExtensionInputs<{\n            [inputName in string]: ExtensionInput;\n          }>;\n        }): Iterable<ExtensionDataValue<any, any>>;\n      };\n}>({\n  type: '@backstage/ExtensionDefinition',\n  versions: ['v1', 'v2'],\n});\n"],"names":[],"mappings":";;AA8BO,MAAM,yBAAA,GAA4B,WAAW,MAAA,CAqDjD;AAAA,EACD,IAAA,EAAM,gCAAA;AAAA,EACN,QAAA,EAAU,CAAC,IAAA,EAAM,IAAI;AACvB,CAAC;;;;"}

package/dist/frontend-internal/src/wiring/InternalExtensionInput.esm.js

@@ -0,0 +1,9 @@
+import { OpaqueType } from '../../../opaque-internal/src/OpaqueType.esm.js';
+
+const OpaqueExtensionInput = OpaqueType.create({
+  type: "@backstage/ExtensionInput",
+  versions: [void 0]
+});
+
+export { OpaqueExtensionInput };
+//# sourceMappingURL=InternalExtensionInput.esm.js.map

package/dist/frontend-internal/src/wiring/InternalExtensionInput.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InternalExtensionInput.esm.js","sources":["../../../../../frontend-internal/src/wiring/InternalExtensionInput.ts"],"sourcesContent":["/*\n * Copyright 2024 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 { ExtensionInput } from '@backstage/frontend-plugin-api';\nimport { OpaqueType } from '@internal/opaque';\n\nexport type ExtensionInputContext = {\n  input: string;\n  kind?: string;\n  name?: string;\n};\n\nexport const OpaqueExtensionInput = OpaqueType.create<{\n  public: ExtensionInput;\n  versions: {\n    readonly version: undefined;\n    readonly context?: ExtensionInputContext;\n    withContext(context: ExtensionInputContext): ExtensionInput;\n  };\n}>({\n  type: '@backstage/ExtensionInput',\n  versions: [undefined],\n});\n"],"names":[],"mappings":";;AAyBO,MAAM,oBAAA,GAAuB,WAAW,MAAA,CAO5C;AAAA,EACD,IAAA,EAAM,2BAAA;AAAA,EACN,QAAA,EAAU,CAAC,MAAS;AACtB,CAAC;;;;"}

package/dist/index.d.ts

@@ -140,10 +140,10 @@ interface ExtensionInput<UExtensionData extends ExtensionDataRef<unknown, string
     singleton: boolean;
     optional: boolean;
 }> {
-    $$type: '@backstage/ExtensionInput';
-    extensionData: Array<UExtensionData>;
-    config: TConfig;
-    replaces?: Array<{
+    readonly $$type: '@backstage/ExtensionInput';
+    readonly extensionData: Array<UExtensionData>;
+    readonly config: TConfig;
+    readonly replaces?: Array<{
         id: string;
         input: string;
     }>;
@@ -245,6 +245,19 @@ type PortableSchema<TOutput, TInput = TOutput> = {
     schema: JsonObject;
 };
 
+/** @public */
+type ExtensionAttachTo = {
+    id: string;
+    input: string;
+} | Array<{
+    id: string;
+    input: string;
+}>;
+/**
+ * @deprecated Use {@link ExtensionAttachTo} instead.
+ * @public
+ */
+type ExtensionAttachToSpec = ExtensionAttachTo;
 /** @public */
 interface Extension<TConfig, TConfigInput = TConfig> {
     $$type: '@backstage/Extension';
@@ -387,7 +400,7 @@ interface ExternalRouteRef<TParams extends AnyRouteRefParams = AnyRouteRefParams
  */
 declare function createExternalRouteRef<TParams extends {
     [param in TParamKeys]: string;
-} | undefined = undefined, TParamKeys extends string = string>(options?: {
+} | undefined = undefined, TParamKeys extends string = string>(config?: {
     /**
      * The parameters that will be provided to the external route reference.
      */
@@ -500,7 +513,7 @@ interface OverridableFrontendPlugin<TRoutes extends {
 } = {
     [id in string]: ExtensionDefinition;
 }> extends FrontendPlugin<TRoutes, TExternalRoutes> {
-    getExtension<TId extends keyof TExtensionMap>(id: TId): TExtensionMap[TId];
+    getExtension<TId extends keyof TExtensionMap>(id: TId): OverridableExtensionDefinition<TExtensionMap[TId]['T']>;
     withOverrides(options: {
         extensions: Array<ExtensionDefinition>;
         /**
@@ -649,9 +662,9 @@ type CreateExtensionBlueprintOptions<TKind extends string, TParams extends objec
     [key in string]: (zImpl: typeof z) => z.ZodType;
 }, UFactoryOutput extends ExtensionDataValue<any, any>, TDataRefs extends {
     [name in string]: ExtensionDataRef;
-}> = {
+}, UParentInputs extends ExtensionDataRef> = {
     kind: TKind;
-    attachTo: ExtensionAttachToSpec;
+    attachTo: ExtensionDefinitionAttachTo<UParentInputs> & VerifyExtensionAttachTo<UOutput, UParentInputs>;
     disabled?: boolean;
     inputs?: TInputs;
     output: Array<UOutput>;
@@ -739,12 +752,12 @@ type AnyParamsInput$1<TParams extends object | ExtensionBlueprintDefineParams> =
  */
 interface ExtensionBlueprint<T extends ExtensionBlueprintParameters = ExtensionBlueprintParameters> {
     dataRefs: T['dataRefs'];
-    make<TName extends string | undefined, TParamsInput extends AnyParamsInput$1<NonNullable<T['params']>>>(args: {
+    make<TName extends string | undefined, TParamsInput extends AnyParamsInput$1<NonNullable<T['params']>>, UParentInputs extends ExtensionDataRef>(args: {
         name?: TName;
-        attachTo?: ExtensionAttachToSpec;
+        attachTo?: ExtensionDefinitionAttachTo<UParentInputs> & VerifyExtensionAttachTo<NonNullable<T['output']>, UParentInputs>;
         disabled?: boolean;
         params: TParamsInput extends ExtensionBlueprintDefineParams ? TParamsInput : T['params'] extends ExtensionBlueprintDefineParams ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `<blueprint>.make({ params: defineParams => defineParams(<params>) })`' : T['params'];
-    }): ExtensionDefinition<{
+    }): OverridableExtensionDefinition<{
         kind: T['kind'];
         name: string | undefined extends TName ? undefined : TName;
         config: T['config'];
@@ -763,9 +776,9 @@ interface ExtensionBlueprint<T extends ExtensionBlueprintParameters = ExtensionB
         [key in string]: (zImpl: typeof z) => z.ZodType;
     }, UFactoryOutput extends ExtensionDataValue<any, any>, UNewOutput extends ExtensionDataRef, TExtraInputs extends {
         [inputName in string]: ExtensionInput;
-    }>(args: {
+    }, UParentInputs extends ExtensionDataRef>(args: {
         name?: TName;
-        attachTo?: ExtensionAttachToSpec;
+        attachTo?: ExtensionDefinitionAttachTo<UParentInputs> & VerifyExtensionAttachTo<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UParentInputs>;
         disabled?: boolean;
         inputs?: TExtraInputs & {
             [KName in keyof T['inputs']]?: `Error: Input '${KName & string}' is already defined in parent definition`;
@@ -787,7 +800,7 @@ interface ExtensionBlueprint<T extends ExtensionBlueprintParameters = ExtensionB
             };
             inputs: Expand<ResolvedExtensionInputs<T['inputs'] & TExtraInputs>>;
         }): Iterable<UFactoryOutput> & VerifyExtensionFactoryOutput<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UFactoryOutput>;
-    }): ExtensionDefinition<{
+    }): OverridableExtensionDefinition<{
         config: (string extends keyof TExtensionConfigSchema ? {} : {
             [key in keyof TExtensionConfigSchema]: z.infer<ReturnType<TExtensionConfigSchema[key]>>;
         }) & T['config'];
@@ -854,9 +867,9 @@ declare function createExtensionBlueprint<TParams extends object | ExtensionBlue
     [inputName in string]: ExtensionInput;
 }, TConfigSchema extends {
     [key in string]: (zImpl: typeof z) => z.ZodType;
-}, UFactoryOutput extends ExtensionDataValue<any, any>, TKind extends string, TDataRefs extends {
+}, UFactoryOutput extends ExtensionDataValue<any, any>, TKind extends string, UParentInputs extends ExtensionDataRef, TDataRefs extends {
     [name in string]: ExtensionDataRef;
-} = never>(options: CreateExtensionBlueprintOptions<TKind, TParams, UOutput, TInputs, TConfigSchema, UFactoryOutput, TDataRefs>): ExtensionBlueprint<{
+} = never>(options: CreateExtensionBlueprintOptions<TKind, TParams, UOutput, TInputs, TConfigSchema, UFactoryOutput, TDataRefs, UParentInputs>): ExtensionBlueprint<{
     kind: TKind;
     params: TParams;
     output: UOutput extends ExtensionDataRef<infer IData, infer IId, infer IConfig> ? ExtensionDataRef<IData, IId, IConfig> : never;
@@ -891,24 +904,77 @@ type PopUnion<U> = ToIntersection<U extends any ? () => U : never> extends () =>
 /** @ignore */
 type JoinStringUnion<U, TDiv extends string = ', ', TResult extends string = ''> = PopUnion<U> extends [infer IRest extends string, infer INext extends string] ? TResult extends '' ? JoinStringUnion<IRest, TDiv, INext> : JoinStringUnion<IRest, TDiv, `${TResult}${TDiv}${INext}`> : TResult;
 /** @ignore */
-type VerifyExtensionFactoryOutput<UDeclaredOutput extends ExtensionDataRef, UFactoryOutput extends ExtensionDataValue<any, any>> = (UDeclaredOutput extends any ? UDeclaredOutput['config']['optional'] extends true ? never : UDeclaredOutput['id'] : never) extends infer IRequiredOutputIds ? [IRequiredOutputIds] extends [UFactoryOutput['id']] ? [UFactoryOutput['id']] extends [UDeclaredOutput['id']] ? {} : `Error: The extension factory has undeclared output(s): ${JoinStringUnion<Exclude<UFactoryOutput['id'], UDeclaredOutput['id']>>}` : `Error: The extension factory is missing the following output(s): ${JoinStringUnion<Exclude<IRequiredOutputIds, UFactoryOutput['id']>>}` : never;
-/** @public */
-type ExtensionAttachToSpec = {
+type RequiredExtensionIds<UExtensionData extends ExtensionDataRef> = UExtensionData extends any ? UExtensionData['config']['optional'] extends true ? never : UExtensionData['id'] : never;
+/** @ignore */
+type VerifyExtensionFactoryOutput<UDeclaredOutput extends ExtensionDataRef, UFactoryOutput extends ExtensionDataValue<any, any>> = [RequiredExtensionIds<UDeclaredOutput>] extends [UFactoryOutput['id']] ? [UFactoryOutput['id']] extends [UDeclaredOutput['id']] ? {} : `Error: The extension factory has undeclared output(s): ${JoinStringUnion<Exclude<UFactoryOutput['id'], UDeclaredOutput['id']>>}` : `Error: The extension factory is missing the following output(s): ${JoinStringUnion<Exclude<RequiredExtensionIds<UDeclaredOutput>, UFactoryOutput['id']>>}`;
+/** @ignore */
+type VerifyExtensionAttachTo<UOutput extends ExtensionDataRef, UParentInput extends ExtensionDataRef> = ExtensionDataRef extends UParentInput ? {} : [RequiredExtensionIds<UParentInput>] extends [RequiredExtensionIds<UOutput>] ? {} : `Error: This parent extension input requires the following extension data, but it is not declared as guaranteed output of this extension: ${JoinStringUnion<Exclude<RequiredExtensionIds<UParentInput>, RequiredExtensionIds<UOutput>>>}`;
+/**
+ * Specifies where an extension should attach in the extension tree.
+ *
+ * @remarks
+ *
+ * A standard attachment point declaration will specify the ID of the parent extension, as well as the name of the input to attach to.
+ *
+ * There are three more advanced forms that are available for more complex use-cases:
+ *
+ * 1. Relative attachment points: using the `relative` property instead of `id`, the attachment point is resolved relative to the current plugin.
+ * 2. Extension input references: using a reference in code to another extension's input in the same plugin. These references are always relative.
+ * 3. Array of attachment points: an array of attachment points can be used to clone and attach to multiple extensions at once.
+ *
+ * @example
+ * ```ts
+ * // Attach to a specific extension by full ID
+ * { id: 'app/routes', input: 'routes' }
+ *
+ * // Attach to an extension in the same plugin by kind
+ * { relative: { kind: 'page' }, input: 'actions' }
+ *
+ * // Attach to a specific input of another extension
+ * const page = ParentBlueprint.make({ ... });
+ * const child = ChildBlueprint.make({ attachTo: page.inputs.children });
+ *
+ * // Attach to multiple parents at once
+ * [
+ *   { id: 'page/home', input: 'widgets' },
+ *   { relative: { kind: 'page' }, input: 'widgets' },
+ * ]
+ * ```
+ *
+ * @public
+ */
+type ExtensionDefinitionAttachTo<UParentInputs extends ExtensionDataRef = ExtensionDataRef> = {
     id: string;
     input: string;
-} | Array<{
+    relative?: never;
+} | {
+    relative: {
+        kind?: string;
+        name?: string;
+    };
+    input: string;
+    id?: never;
+} | ExtensionInput<UParentInputs> | Array<{
     id: string;
     input: string;
-}>;
+    relative?: never;
+} | {
+    relative: {
+        kind?: string;
+        name?: string;
+    };
+    input: string;
+    id?: never;
+} | ExtensionInput<UParentInputs>>;
 /** @public */
 type CreateExtensionOptions<TKind extends string | undefined, TName extends string | undefined, UOutput extends ExtensionDataRef, TInputs extends {
     [inputName in string]: ExtensionInput;
 }, TConfigSchema extends {
     [key: string]: (zImpl: typeof z) => z.ZodType;
-}, UFactoryOutput extends ExtensionDataValue<any, any>> = {
+}, UFactoryOutput extends ExtensionDataValue<any, any>, UParentInputs extends ExtensionDataRef> = {
     kind?: TKind;
     name?: TName;
-    attachTo: ExtensionAttachToSpec;
+    attachTo: ExtensionDefinitionAttachTo<UParentInputs> & VerifyExtensionAttachTo<UOutput, UParentInputs>;
     disabled?: boolean;
     inputs?: TInputs;
     output: Array<UOutput>;
@@ -947,15 +1013,24 @@ type ExtensionDefinitionParameters = {
  */
 type AnyParamsInput<TParams extends object | ExtensionBlueprintDefineParams> = TParams extends ExtensionBlueprintDefineParams<infer IParams> ? IParams | ((define: TParams) => ReturnType<TParams>) : TParams | ((define: ExtensionBlueprintDefineParams<TParams, TParams>) => ReturnType<ExtensionBlueprintDefineParams<TParams, TParams>>);
 /** @public */
-type ExtensionDefinition<T extends ExtensionDefinitionParameters = ExtensionDefinitionParameters> = {
+interface ExtensionDefinition<TParams extends ExtensionDefinitionParameters = ExtensionDefinitionParameters> {
     $$type: '@backstage/ExtensionDefinition';
-    readonly T: T;
+    readonly T: TParams;
+}
+/** @public */
+interface OverridableExtensionDefinition<T extends ExtensionDefinitionParameters = ExtensionDefinitionParameters> extends ExtensionDefinition<T> {
+    /**
+     * References to the inputs of this extension, which can be used to attach child extensions.
+     */
+    readonly inputs: {
+        [K in keyof T['inputs']]: ExtensionInput<T['inputs'][K] extends ExtensionInput<infer IData> ? IData : never>;
+    };
     override<TExtensionConfigSchema extends {
         [key in string]: (zImpl: typeof z) => z.ZodType;
     }, UFactoryOutput extends ExtensionDataValue<any, any>, UNewOutput extends ExtensionDataRef, TExtraInputs extends {
         [inputName in string]: ExtensionInput;
-    }, TParamsInput extends AnyParamsInput<NonNullable<T['params']>>>(args: Expand<{
-        attachTo?: ExtensionAttachToSpec;
+    }, TParamsInput extends AnyParamsInput<NonNullable<T['params']>>, UParentInputs extends ExtensionDataRef>(args: Expand<{
+        attachTo?: ExtensionDefinitionAttachTo<UParentInputs> & VerifyExtensionAttachTo<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UParentInputs>;
         disabled?: boolean;
         inputs?: TExtraInputs & {
             [KName in keyof T['inputs']]?: `Error: Input '${KName & string}' is already defined in parent definition`;
@@ -981,7 +1056,7 @@ type ExtensionDefinition<T extends ExtensionDefinitionParameters = ExtensionDefi
         }): Iterable<UFactoryOutput>;
     } & ([T['params']] extends [never] ? {} : {
         params?: TParamsInput extends ExtensionBlueprintDefineParams ? TParamsInput : T['params'] extends ExtensionBlueprintDefineParams ? 'Error: This blueprint uses advanced parameter types and requires you to pass parameters as using the following callback syntax: `originalFactory(defineParams => defineParams(<params>))`' : Partial<T['params']>;
-    })> & VerifyExtensionFactoryOutput<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UFactoryOutput>): ExtensionDefinition<{
+    })> & VerifyExtensionFactoryOutput<ExtensionDataRef extends UNewOutput ? NonNullable<T['output']> : UNewOutput, UFactoryOutput>): OverridableExtensionDefinition<{
         kind: T['kind'];
         name: T['name'];
         output: ExtensionDataRef extends UNewOutput ? T['output'] : UNewOutput;
@@ -993,7 +1068,7 @@ type ExtensionDefinition<T extends ExtensionDefinitionParameters = ExtensionDefi
             [key in keyof TExtensionConfigSchema]: ReturnType<TExtensionConfigSchema[key]>;
         }>>;
     }>;
-};
+}
 /**
  * Creates a new extension definition for installation in a Backstage app.
  *
@@ -1033,7 +1108,7 @@ declare function createExtension<UOutput extends ExtensionDataRef, TInputs exten
     [inputName in string]: ExtensionInput;
 }, TConfigSchema extends {
     [key: string]: (zImpl: typeof z) => z.ZodType;
-}, UFactoryOutput extends ExtensionDataValue<any, any>, const TKind extends string | undefined = undefined, const TName extends string | undefined = undefined>(options: CreateExtensionOptions<TKind, TName, UOutput, TInputs, TConfigSchema, UFactoryOutput>): ExtensionDefinition<{
+}, UFactoryOutput extends ExtensionDataValue<any, any>, const TKind extends string | undefined = undefined, const TName extends string | undefined = undefined, UParentInputs extends ExtensionDataRef = ExtensionDataRef>(options: CreateExtensionOptions<TKind, TName, UOutput, TInputs, TConfigSchema, UFactoryOutput, UParentInputs>): OverridableExtensionDefinition<{
     config: string extends keyof TConfigSchema ? {} : {
         [key in keyof TConfigSchema]: z.infer<ReturnType<TConfigSchema[key]>>;
     };
@@ -1077,7 +1152,7 @@ declare function createFrontendFeatureLoader(options: CreateFrontendFeatureLoade
  */
 interface AppNodeSpec {
     readonly id: string;
-    readonly attachTo: ExtensionAttachToSpec;
+    readonly attachTo: ExtensionAttachTo;
     readonly extension: Extension<unknown, unknown>;
     readonly disabled: boolean;
     readonly config?: unknown;
@@ -1944,4 +2019,4 @@ declare const SwappableComponentBlueprint: ExtensionBlueprint<{
     };
 }>;
 
-export { type AnalyticsApi, AnalyticsContext, type AnalyticsContextValue, type AnalyticsEvent, type AnalyticsEventAttributes, type AnalyticsImplementation, AnalyticsImplementationBlueprint, type AnalyticsImplementationFactory, type AnalyticsTracker, type AnyExtensionDataRef, type AnyRouteRefParams, ApiBlueprint, type AppNode, type AppNodeEdges, type AppNodeInstance, type AppNodeSpec, AppRootElementBlueprint, AppRootWrapperBlueprint, type AppTree, type AppTreeApi, type ConfigurableExtensionDataRef, type CreateExtensionBlueprintOptions, type CreateExtensionOptions, type CreateFrontendFeatureLoaderOptions, type CreateFrontendModuleOptions, type CreateSwappableComponentOptions, type DialogApi, type DialogApiDialog, ErrorDisplay, type ErrorDisplayProps, type Extension, type ExtensionAttachToSpec, type ExtensionBlueprint, type ExtensionBlueprintDefineParams, type ExtensionBlueprintParameters, type ExtensionBlueprintParams, ExtensionBoundary, type ExtensionBoundaryProps, type ExtensionDataContainer, type ExtensionDataRef, type ExtensionDataRefToValue, type ExtensionDataValue, type ExtensionDefinition, type ExtensionDefinitionParameters, type ExtensionFactoryMiddleware, type ExtensionInput, type ExternalRouteRef, type FeatureFlagConfig, type FrontendFeature, type FrontendFeatureLoader, type FrontendModule, type FrontendPlugin, type FrontendPluginInfo, type FrontendPluginInfoOptions, IconBundleBlueprint, type IconComponent, type IconsApi, NavContentBlueprint, type NavContentComponent, type NavContentComponentProps, NavItemBlueprint, NotFoundErrorPage, type NotFoundErrorPageProps, type OverridableFrontendPlugin, PageBlueprint, type PluginOptions, type PortableSchema, Progress, type ProgressProps, type ResolvedExtensionInput, type ResolvedExtensionInputs, type RouteFunc, type RouteRef, type RouteResolutionApi, RouterBlueprint, SignInPageBlueprint, type SubRouteRef, SwappableComponentBlueprint, type SwappableComponentRef, type SwappableComponentsApi, ThemeBlueprint, TranslationBlueprint, analyticsApiRef, appTreeApiRef, coreExtensionData, createExtension, createExtensionBlueprint, createExtensionBlueprintParams, createExtensionDataRef, createExtensionInput, createExternalRouteRef, createFrontendFeatureLoader, createFrontendModule, createFrontendPlugin, createRouteRef, createSubRouteRef, createSwappableComponent, dialogApiRef, iconsApiRef, routeResolutionApiRef, swappableComponentsApiRef, useAnalytics, useAppNode, useRouteRef, useRouteRefParams };
+export { type AnalyticsApi, AnalyticsContext, type AnalyticsContextValue, type AnalyticsEvent, type AnalyticsEventAttributes, type AnalyticsImplementation, AnalyticsImplementationBlueprint, type AnalyticsImplementationFactory, type AnalyticsTracker, type AnyExtensionDataRef, type AnyRouteRefParams, ApiBlueprint, type AppNode, type AppNodeEdges, type AppNodeInstance, type AppNodeSpec, AppRootElementBlueprint, AppRootWrapperBlueprint, type AppTree, type AppTreeApi, type ConfigurableExtensionDataRef, type CreateExtensionBlueprintOptions, type CreateExtensionOptions, type CreateFrontendFeatureLoaderOptions, type CreateFrontendModuleOptions, type CreateSwappableComponentOptions, type DialogApi, type DialogApiDialog, ErrorDisplay, type ErrorDisplayProps, type Extension, type ExtensionAttachTo, type ExtensionAttachToSpec, type ExtensionBlueprint, type ExtensionBlueprintDefineParams, type ExtensionBlueprintParameters, type ExtensionBlueprintParams, ExtensionBoundary, type ExtensionBoundaryProps, type ExtensionDataContainer, type ExtensionDataRef, type ExtensionDataRefToValue, type ExtensionDataValue, type ExtensionDefinition, type ExtensionDefinitionAttachTo, type ExtensionDefinitionParameters, type ExtensionFactoryMiddleware, type ExtensionInput, type ExternalRouteRef, type FeatureFlagConfig, type FrontendFeature, type FrontendFeatureLoader, type FrontendModule, type FrontendPlugin, type FrontendPluginInfo, type FrontendPluginInfoOptions, IconBundleBlueprint, type IconComponent, type IconsApi, NavContentBlueprint, type NavContentComponent, type NavContentComponentProps, NavItemBlueprint, NotFoundErrorPage, type NotFoundErrorPageProps, type OverridableExtensionDefinition, type OverridableFrontendPlugin, PageBlueprint, type PluginOptions, type PortableSchema, Progress, type ProgressProps, type ResolvedExtensionInput, type ResolvedExtensionInputs, type RouteFunc, type RouteRef, type RouteResolutionApi, RouterBlueprint, SignInPageBlueprint, type SubRouteRef, SwappableComponentBlueprint, type SwappableComponentRef, type SwappableComponentsApi, ThemeBlueprint, TranslationBlueprint, analyticsApiRef, appTreeApiRef, coreExtensionData, createExtension, createExtensionBlueprint, createExtensionBlueprintParams, createExtensionDataRef, createExtensionInput, createExternalRouteRef, createFrontendFeatureLoader, createFrontendModule, createFrontendPlugin, createRouteRef, createSubRouteRef, createSwappableComponent, dialogApiRef, iconsApiRef, routeResolutionApiRef, swappableComponentsApiRef, useAnalytics, useAppNode, useRouteRef, useRouteRefParams };

package/dist/routing/ExternalRouteRef.esm.js

@@ -1,25 +1,41 @@
-import { RouteRefImpl } from './RouteRef.esm.js';
 import { describeParentCallSite } from './describeParentCallSite.esm.js';
+import { OpaqueExternalRouteRef } from '../frontend-internal/src/routing/OpaqueExternalRouteRef.esm.js';
+import '../frontend-internal/src/routing/OpaqueRouteRef.esm.js';
+import '../frontend-internal/src/routing/OpaqueSubRouteRef.esm.js';
 
-class ExternalRouteRefImpl extends RouteRefImpl {
-  $$type = "@backstage/ExternalRouteRef";
-  params;
-  defaultTarget;
-  constructor(params = [], defaultTarget, creationSite) {
-    super(params, creationSite);
-    this.params = params;
-    this.defaultTarget = defaultTarget;
-  }
-  getDefaultTarget() {
-    return this.defaultTarget;
-  }
-}
-function createExternalRouteRef(options) {
-  return new ExternalRouteRefImpl(
-    options?.params,
-    options?.defaultTarget,
-    describeParentCallSite()
-  );
+function createExternalRouteRef(config) {
+  const params = config?.params ?? [];
+  const creationSite = describeParentCallSite();
+  let id = void 0;
+  return OpaqueExternalRouteRef.createInstance("v1", {
+    T: void 0,
+    getParams() {
+      return params;
+    },
+    getDescription() {
+      if (id) {
+        return id;
+      }
+      return `created at '${creationSite}'`;
+    },
+    getDefaultTarget() {
+      return config?.defaultTarget;
+    },
+    setId(newId) {
+      if (!newId) {
+        throw new Error(`ExternalRouteRef id must be a non-empty string`);
+      }
+      if (id && id !== newId) {
+        throw new Error(
+          `ExternalRouteRef was referenced twice as both '${id}' and '${newId}'`
+        );
+      }
+      id = newId;
+    },
+    toString() {
+      return `externalRouteRef{id=${id},at='${creationSite}'}`;
+    }
+  });
 }
 
 export { createExternalRouteRef };

package/dist/routing/ExternalRouteRef.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExternalRouteRef.esm.js","sources":["../../src/routing/ExternalRouteRef.ts"],"sourcesContent":["/*\n * Copyright 2020 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 { RouteRefImpl } from './RouteRef';\nimport { describeParentCallSite } from './describeParentCallSite';\nimport { AnyRouteRefParams } from './types';\n\n/**\n * Route descriptor, to be later bound to a concrete route by the app. Used to implement cross-plugin route references.\n *\n * @remarks\n *\n * See {@link https://backstage.io/docs/plugins/composability#routing-system}.\n *\n * @public\n */\nexport interface ExternalRouteRef<\n  TParams extends AnyRouteRefParams = AnyRouteRefParams,\n> {\n  readonly $$type: '@backstage/ExternalRouteRef';\n  readonly T: TParams;\n}\n\n/** @internal */\nexport interface InternalExternalRouteRef<\n  TParams extends AnyRouteRefParams = AnyRouteRefParams,\n> extends ExternalRouteRef<TParams> {\n  readonly version: 'v1';\n  getParams(): string[];\n  getDescription(): string;\n  getDefaultTarget(): string | undefined;\n\n  setId(id: string): void;\n}\n\n/** @internal */\nexport function toInternalExternalRouteRef<\n  TParams extends AnyRouteRefParams = AnyRouteRefParams,\n>(resource: ExternalRouteRef<TParams>): InternalExternalRouteRef<TParams> {\n  const r = resource as InternalExternalRouteRef<TParams>;\n  if (r.$$type !== '@backstage/ExternalRouteRef') {\n    throw new Error(`Invalid ExternalRouteRef, bad type '${r.$$type}'`);\n  }\n\n  return r;\n}\n\n/** @internal */\nexport function isExternalRouteRef(opaque: {\n  $$type: string;\n}): opaque is ExternalRouteRef {\n  return opaque.$$type === '@backstage/ExternalRouteRef';\n}\n\n/** @internal */\nclass ExternalRouteRefImpl\n  extends RouteRefImpl\n  implements InternalExternalRouteRef\n{\n  readonly $$type = '@backstage/ExternalRouteRef' as any;\n  readonly params: string[];\n  readonly defaultTarget: string | undefined;\n\n  constructor(\n    params: string[] = [],\n    defaultTarget: string | undefined,\n    creationSite: string,\n  ) {\n    super(params, creationSite);\n    this.params = params;\n    this.defaultTarget = defaultTarget;\n  }\n\n  getDefaultTarget() {\n    return this.defaultTarget;\n  }\n}\n\n/**\n * Creates a route descriptor, to be later bound to a concrete route by the app. Used to implement cross-plugin route references.\n *\n * @remarks\n *\n * See {@link https://backstage.io/docs/plugins/composability#routing-system}.\n *\n * @param options - Description of the route reference to be created.\n * @public\n */\nexport function createExternalRouteRef<\n  TParams extends { [param in TParamKeys]: string } | undefined = undefined,\n  TParamKeys extends string = string,\n>(options?: {\n  /**\n   * The parameters that will be provided to the external route reference.\n   */\n  readonly params?: string extends TParamKeys\n    ? (keyof TParams)[]\n    : TParamKeys[];\n\n  /**\n   * The route (typically in another plugin) that this should map to by default.\n   *\n   * The string is expected to be on the standard `<plugin id>.<route id>` form,\n   * for example `techdocs.docRoot`.\n   */\n  defaultTarget?: string;\n}): ExternalRouteRef<\n  keyof TParams extends never\n    ? undefined\n    : string extends TParamKeys\n    ? TParams\n    : { [param in TParamKeys]: string }\n> {\n  return new ExternalRouteRefImpl(\n    options?.params as string[] | undefined,\n    options?.defaultTarget,\n    describeParentCallSite(),\n  );\n}\n"],"names":[],"mappings":";;;AAoEA,MAAM,6BACI,YAAA,CAEV;AAAA,EACW,MAAA,GAAS,6BAAA;AAAA,EACT,MAAA;AAAA,EACA,aAAA;AAAA,EAET,WAAA,CACE,MAAA,GAAmB,EAAC,EACpB,eACA,YAAA,EACA;AACA,IAAA,KAAA,CAAM,QAAQ,YAAY,CAAA;AAC1B,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,aAAA,GAAgB,aAAA;AAAA,EACvB;AAAA,EAEA,gBAAA,GAAmB;AACjB,IAAA,OAAO,IAAA,CAAK,aAAA;AAAA,EACd;AACF;AAYO,SAAS,uBAGd,OAAA,EAqBA;AACA,EAAA,OAAO,IAAI,oBAAA;AAAA,IACT,OAAA,EAAS,MAAA;AAAA,IACT,OAAA,EAAS,aAAA;AAAA,IACT,sBAAA;AAAuB,GACzB;AACF;;;;"}
+{"version":3,"file":"ExternalRouteRef.esm.js","sources":["../../src/routing/ExternalRouteRef.ts"],"sourcesContent":["/*\n * Copyright 2020 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 { OpaqueExternalRouteRef } from '@internal/frontend';\nimport { describeParentCallSite } from './describeParentCallSite';\nimport { AnyRouteRefParams } from './types';\n\n/**\n * Route descriptor, to be later bound to a concrete route by the app. Used to implement cross-plugin route references.\n *\n * @remarks\n *\n * See {@link https://backstage.io/docs/plugins/composability#routing-system}.\n *\n * @public\n */\nexport interface ExternalRouteRef<\n  TParams extends AnyRouteRefParams = AnyRouteRefParams,\n> {\n  readonly $$type: '@backstage/ExternalRouteRef';\n  readonly T: TParams;\n}\n\n/** @internal */\nexport interface InternalExternalRouteRef<\n  TParams extends AnyRouteRefParams = AnyRouteRefParams,\n> extends ExternalRouteRef<TParams> {\n  readonly version: 'v1';\n  getParams(): string[];\n  getDescription(): string;\n  getDefaultTarget(): string | undefined;\n\n  setId(id: string): void;\n}\n\n/** @internal */\nexport function toInternalExternalRouteRef<\n  TParams extends AnyRouteRefParams = AnyRouteRefParams,\n>(resource: ExternalRouteRef<TParams>): InternalExternalRouteRef<TParams> {\n  const r = resource as InternalExternalRouteRef<TParams>;\n  if (r.$$type !== '@backstage/ExternalRouteRef') {\n    throw new Error(`Invalid ExternalRouteRef, bad type '${r.$$type}'`);\n  }\n\n  return r;\n}\n\n/**\n * Creates a route descriptor, to be later bound to a concrete route by the app. Used to implement cross-plugin route references.\n *\n * @remarks\n *\n * See {@link https://backstage.io/docs/plugins/composability#routing-system}.\n *\n * @param options - Description of the route reference to be created.\n * @public\n */\nexport function createExternalRouteRef<\n  TParams extends { [param in TParamKeys]: string } | undefined = undefined,\n  TParamKeys extends string = string,\n>(config?: {\n  /**\n   * The parameters that will be provided to the external route reference.\n   */\n  readonly params?: string extends TParamKeys\n    ? (keyof TParams)[]\n    : TParamKeys[];\n\n  /**\n   * The route (typically in another plugin) that this should map to by default.\n   *\n   * The string is expected to be on the standard `<plugin id>.<route id>` form,\n   * for example `techdocs.docRoot`.\n   */\n  defaultTarget?: string;\n}): ExternalRouteRef<\n  keyof TParams extends never\n    ? undefined\n    : string extends TParamKeys\n    ? TParams\n    : { [param in TParamKeys]: string }\n> {\n  const params = (config?.params ?? []) as string[];\n  const creationSite = describeParentCallSite();\n\n  let id: string | undefined = undefined;\n\n  return OpaqueExternalRouteRef.createInstance('v1', {\n    T: undefined as unknown as TParams,\n    getParams() {\n      return params;\n    },\n    getDescription() {\n      if (id) {\n        return id;\n      }\n      return `created at '${creationSite}'`;\n    },\n    getDefaultTarget() {\n      return config?.defaultTarget;\n    },\n    setId(newId: string) {\n      if (!newId) {\n        throw new Error(`ExternalRouteRef id must be a non-empty string`);\n      }\n      if (id && id !== newId) {\n        throw new Error(\n          `ExternalRouteRef was referenced twice as both '${id}' and '${newId}'`,\n        );\n      }\n      id = newId;\n    },\n    toString(): string {\n      return `externalRouteRef{id=${id},at='${creationSite}'}`;\n    },\n  });\n}\n"],"names":[],"mappings":";;;;;AAsEO,SAAS,uBAGd,MAAA,EAqBA;AACA,EAAA,MAAM,MAAA,GAAU,MAAA,EAAQ,MAAA,IAAU,EAAC;AACnC,EAAA,MAAM,eAAe,sBAAA,EAAuB;AAE5C,EAAA,IAAI,EAAA,GAAyB,MAAA;AAE7B,EAAA,OAAO,sBAAA,CAAuB,eAAe,IAAA,EAAM;AAAA,IACjD,CAAA,EAAG,MAAA;AAAA,IACH,SAAA,GAAY;AACV,MAAA,OAAO,MAAA;AAAA,IACT,CAAA;AAAA,IACA,cAAA,GAAiB;AACf,MAAA,IAAI,EAAA,EAAI;AACN,QAAA,OAAO,EAAA;AAAA,MACT;AACA,MAAA,OAAO,eAAe,YAAY,CAAA,CAAA,CAAA;AAAA,IACpC,CAAA;AAAA,IACA,gBAAA,GAAmB;AACjB,MAAA,OAAO,MAAA,EAAQ,aAAA;AAAA,IACjB,CAAA;AAAA,IACA,MAAM,KAAA,EAAe;AACnB,MAAA,IAAI,CAAC,KAAA,EAAO;AACV,QAAA,MAAM,IAAI,MAAM,CAAA,8CAAA,CAAgD,CAAA;AAAA,MAClE;AACA,MAAA,IAAI,EAAA,IAAM,OAAO,KAAA,EAAO;AACtB,QAAA,MAAM,IAAI,KAAA;AAAA,UACR,CAAA,+CAAA,EAAkD,EAAE,CAAA,OAAA,EAAU,KAAK,CAAA,CAAA;AAAA,SACrE;AAAA,MACF;AACA,MAAA,EAAA,GAAK,KAAA;AAAA,IACP,CAAA;AAAA,IACA,QAAA,GAAmB;AACjB,MAAA,OAAO,CAAA,oBAAA,EAAuB,EAAE,CAAA,KAAA,EAAQ,YAAY,CAAA,EAAA,CAAA;AAAA,IACtD;AAAA,GACD,CAAA;AACH;;;;"}