@backstage/plugin-app-react 0.1.1-next.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @backstage/plugin-app-react
 
+## 0.2.0
+
+### Minor Changes
+
+- a2133be: Added new `NavContentNavItem`, `NavContentNavItems`, and `navItems` prop to `NavContentComponentProps` for auto-discovering navigation items from page extensions. The new `navItems` collection supports `take(id)` and `rest()` methods for placing specific items in custom sidebar positions, as well as `withComponent(Component)` which returns a `NavContentNavItemsWithComponent` for rendering items directly as elements. The existing `items` prop is now deprecated in favor of `navItems`.
+
+### Patch Changes
+
+- ef6916e: Added `IconElement` type as a replacement for the deprecated `IconComponent`. The `IconsApi` now has a new `icon()` method that returns `IconElement`, while the existing `getIcon()` method is deprecated. The `IconBundleBlueprint` now accepts both `IconComponent` and `IconElement` values.
+- 409af72: Internal refactor to move implementation of blueprints from `@backstage/frontend-plugin-api` to this package.
+- Updated dependencies
+  - @backstage/frontend-plugin-api@0.14.0
+  - @backstage/core-plugin-api@1.12.3
+
 ## 0.1.1-next.0
 
 ### Patch Changes

package/dist/blueprints/IconBundleBlueprint.esm.js

@@ -5,9 +5,7 @@ const IconBundleBlueprint = createExtensionBlueprint({
   kind: "icon-bundle",
   attachTo: { id: "api:app/icons", input: "icons" },
   output: [iconsDataRef],
-  factory: (params) => [
-    iconsDataRef(params.icons)
-  ],
+  factory: (params) => [iconsDataRef(params.icons)],
   dataRefs: {
     icons: iconsDataRef
   }

package/dist/blueprints/IconBundleBlueprint.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"IconBundleBlueprint.esm.js","sources":["../../src/blueprints/IconBundleBlueprint.ts"],"sourcesContent":["/*\n * Copyright 2026 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 { IconComponent } from '@backstage/frontend-plugin-api';\nimport {\n  createExtensionBlueprint,\n  createExtensionDataRef,\n} from '@backstage/frontend-plugin-api';\n\nconst iconsDataRef = createExtensionDataRef<{\n  [key in string]: IconComponent;\n}>().with({ id: 'core.icons' });\n\n/**\n * Creates an extension that adds icon bundles to your app. This blueprint is limited to use by the app plugin.\n *\n * @public\n */\nexport const IconBundleBlueprint = createExtensionBlueprint({\n  kind: 'icon-bundle',\n  attachTo: { id: 'api:app/icons', input: 'icons' },\n  output: [iconsDataRef],\n  factory: (params: { icons: { [key in string]: IconComponent } }) => [\n    iconsDataRef(params.icons),\n  ],\n  dataRefs: {\n    icons: iconsDataRef,\n  },\n});\n"],"names":[],"mappings":";;AAsBA,MAAM,eAAe,sBAAA,EAElB,CAAE,KAAK,EAAE,EAAA,EAAI,cAAc,CAAA;AAOvB,MAAM,sBAAsB,wBAAA,CAAyB;AAAA,EAC1D,IAAA,EAAM,aAAA;AAAA,EACN,QAAA,EAAU,EAAE,EAAA,EAAI,eAAA,EAAiB,OAAO,OAAA,EAAQ;AAAA,EAChD,MAAA,EAAQ,CAAC,YAAY,CAAA;AAAA,EACrB,OAAA,EAAS,CAAC,MAAA,KAA0D;AAAA,IAClE,YAAA,CAAa,OAAO,KAAK;AAAA,GAC3B;AAAA,EACA,QAAA,EAAU;AAAA,IACR,KAAA,EAAO;AAAA;AAEX,CAAC;;;;"}
+{"version":3,"file":"IconBundleBlueprint.esm.js","sources":["../../src/blueprints/IconBundleBlueprint.ts"],"sourcesContent":["/*\n * Copyright 2026 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 { IconComponent, IconElement } from '@backstage/frontend-plugin-api';\nimport {\n  createExtensionBlueprint,\n  createExtensionDataRef,\n} from '@backstage/frontend-plugin-api';\n\nconst iconsDataRef = createExtensionDataRef<{\n  [key in string]: IconComponent | IconElement;\n}>().with({ id: 'core.icons' });\n\n/**\n * Creates an extension that adds icon bundles to your app. This blueprint is limited to use by the app plugin.\n *\n * @public\n */\nexport const IconBundleBlueprint = createExtensionBlueprint({\n  kind: 'icon-bundle',\n  attachTo: { id: 'api:app/icons', input: 'icons' },\n  output: [iconsDataRef],\n  factory: (params: {\n    icons: { [key in string]: IconComponent | IconElement };\n  }) => [iconsDataRef(params.icons)],\n  dataRefs: {\n    icons: iconsDataRef,\n  },\n});\n"],"names":[],"mappings":";;AAsBA,MAAM,eAAe,sBAAA,EAElB,CAAE,KAAK,EAAE,EAAA,EAAI,cAAc,CAAA;AAOvB,MAAM,sBAAsB,wBAAA,CAAyB;AAAA,EAC1D,IAAA,EAAM,aAAA;AAAA,EACN,QAAA,EAAU,EAAE,EAAA,EAAI,eAAA,EAAiB,OAAO,OAAA,EAAQ;AAAA,EAChD,MAAA,EAAQ,CAAC,YAAY,CAAA;AAAA,EACrB,SAAS,CAAC,MAAA,KAEJ,CAAC,YAAA,CAAa,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,EACjC,QAAA,EAAU;AAAA,IACR,KAAA,EAAO;AAAA;AAEX,CAAC;;;;"}

package/dist/blueprints/NavContentBlueprint.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"NavContentBlueprint.esm.js","sources":["../../src/blueprints/NavContentBlueprint.ts"],"sourcesContent":["/*\n * Copyright 2026 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 { IconComponent, RouteRef } from '@backstage/frontend-plugin-api';\nimport {\n  createExtensionBlueprint,\n  createExtensionDataRef,\n} from '@backstage/frontend-plugin-api';\n\n/**\n * The props for the {@link NavContentComponent}.\n *\n * @public\n */\nexport interface NavContentComponentProps {\n  /**\n   * The nav items available to the component. These are all the items created\n   * with the {@link @backstage/frontend-plugin-api#NavItemBlueprint} in the app.\n   *\n   * In addition to the original properties from the nav items, these also\n   * include a resolved route path as `to`, and duplicated `title` as `text` to\n   * simplify rendering.\n   */\n  items: Array<{\n    // Original props from nav items\n    icon: IconComponent;\n    title: string;\n    routeRef: RouteRef<undefined>;\n\n    // Additional props to simplify item rendering\n    to: string;\n    text: string;\n  }>;\n}\n\n/**\n * A component that renders the nav bar content, to be passed to the {@link NavContentBlueprint}.\n *\n * @public\n */\nexport type NavContentComponent = (\n  props: NavContentComponentProps,\n) => JSX.Element | null;\n\nconst componentDataRef = createExtensionDataRef<NavContentComponent>().with({\n  id: 'core.nav-content.component',\n});\n\n/**\n * Creates an extension that replaces the entire nav bar with your own component. This blueprint is limited to use by the app plugin.\n *\n * @public\n */\nexport const NavContentBlueprint = createExtensionBlueprint({\n  kind: 'nav-content',\n  attachTo: { id: 'app/nav', input: 'content' },\n  output: [componentDataRef],\n  dataRefs: {\n    component: componentDataRef,\n  },\n  *factory(params: { component: NavContentComponent }) {\n    yield componentDataRef(params.component);\n  },\n});\n"],"names":[],"mappings":";;AAyDA,MAAM,gBAAA,GAAmB,sBAAA,EAA4C,CAAE,IAAA,CAAK;AAAA,EAC1E,EAAA,EAAI;AACN,CAAC,CAAA;AAOM,MAAM,sBAAsB,wBAAA,CAAyB;AAAA,EAC1D,IAAA,EAAM,aAAA;AAAA,EACN,QAAA,EAAU,EAAE,EAAA,EAAI,SAAA,EAAW,OAAO,SAAA,EAAU;AAAA,EAC5C,MAAA,EAAQ,CAAC,gBAAgB,CAAA;AAAA,EACzB,QAAA,EAAU;AAAA,IACR,SAAA,EAAW;AAAA,GACb;AAAA,EACA,CAAC,QAAQ,MAAA,EAA4C;AACnD,IAAA,MAAM,gBAAA,CAAiB,OAAO,SAAS,CAAA;AAAA,EACzC;AACF,CAAC;;;;"}
+{"version":3,"file":"NavContentBlueprint.esm.js","sources":["../../src/blueprints/NavContentBlueprint.ts"],"sourcesContent":["/*\n * Copyright 2026 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { ComponentType } from 'react';\nimport {\n  AppNode,\n  IconComponent,\n  IconElement,\n  RouteRef,\n} from '@backstage/frontend-plugin-api';\nimport {\n  createExtensionBlueprint,\n  createExtensionDataRef,\n} from '@backstage/frontend-plugin-api';\n\n/**\n * A navigation item auto-discovered from a page extension in the app.\n *\n * @public\n */\nexport interface NavContentNavItem {\n  /** The app node of the page extension that this nav item points to */\n  node: AppNode;\n  /** The resolved route path */\n  href: string;\n  /** The display title */\n  title: string;\n  /** The display icon */\n  icon: IconElement;\n  /** The route ref of the source page */\n  routeRef: RouteRef;\n}\n\n/**\n * A pre-bound renderer that wraps {@link NavContentNavItems} with a component,\n * so that `take` and `rest` return rendered elements directly.\n *\n * @public\n */\nexport interface NavContentNavItemsWithComponent {\n  /** Render and take a specific item by extension ID. Returns null if not found. */\n  take(id: string): JSX.Element | null;\n  /** Render all remaining items not yet taken, optionally sorted. */\n  rest(options?: { sortBy?: 'title' }): JSX.Element[];\n}\n\n/**\n * A collection of nav items that supports picking specific items by ID\n * and retrieving whatever remains. Created fresh for each render.\n *\n * @public\n */\nexport interface NavContentNavItems {\n  /** Take an item by extension ID, removing it from the collection. */\n  take(id: string): NavContentNavItem | undefined;\n  /** All items not yet taken. */\n  rest(): NavContentNavItem[];\n  /** Create a copy of the collection preserving the current taken state. */\n  clone(): NavContentNavItems;\n  /** Create a renderer that wraps take/rest to return pre-rendered elements. */\n  withComponent(\n    Component: ComponentType<NavContentNavItem>,\n  ): NavContentNavItemsWithComponent;\n}\n\n/**\n * The props for the {@link NavContentComponent}.\n *\n * @public\n */\nexport interface NavContentComponentProps {\n  /**\n   * Nav items auto-discovered from page extensions, with take/rest semantics\n   * for placing specific items in specific positions.\n   */\n  navItems: NavContentNavItems;\n\n  /**\n   * Flat list of nav items for simple rendering. Use `navItems` for more\n   * control over item placement.\n   *\n   * @deprecated Use `navItems` instead.\n   */\n  items: Array<{\n    icon: IconComponent;\n    title: string;\n    routeRef: RouteRef<undefined>;\n    to: string;\n    text: string;\n  }>;\n}\n\n/**\n * A component that renders the nav bar content, to be passed to the {@link NavContentBlueprint}.\n *\n * @public\n */\nexport type NavContentComponent = (\n  props: NavContentComponentProps,\n) => JSX.Element | null;\n\nconst componentDataRef = createExtensionDataRef<NavContentComponent>().with({\n  id: 'core.nav-content.component',\n});\n\n/**\n * Creates an extension that replaces the entire nav bar with your own component. This blueprint is limited to use by the app plugin.\n *\n * @public\n */\nexport const NavContentBlueprint = createExtensionBlueprint({\n  kind: 'nav-content',\n  attachTo: { id: 'app/nav', input: 'content' },\n  output: [componentDataRef],\n  dataRefs: {\n    component: componentDataRef,\n  },\n  *factory(params: { component: NavContentComponent }) {\n    yield componentDataRef(params.component);\n  },\n});\n"],"names":[],"mappings":";;AAkHA,MAAM,gBAAA,GAAmB,sBAAA,EAA4C,CAAE,IAAA,CAAK;AAAA,EAC1E,EAAA,EAAI;AACN,CAAC,CAAA;AAOM,MAAM,sBAAsB,wBAAA,CAAyB;AAAA,EAC1D,IAAA,EAAM,aAAA;AAAA,EACN,QAAA,EAAU,EAAE,EAAA,EAAI,SAAA,EAAW,OAAO,SAAA,EAAU;AAAA,EAC5C,MAAA,EAAQ,CAAC,gBAAgB,CAAA;AAAA,EACzB,QAAA,EAAU;AAAA,IACR,SAAA,EAAW;AAAA,GACb;AAAA,EACA,CAAC,QAAQ,MAAA,EAA4C;AACnD,IAAA,MAAM,gBAAA,CAAiB,OAAO,SAAS,CAAA;AAAA,EACzC;AACF,CAAC;;;;"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _backstage_frontend_plugin_api from '@backstage/frontend-plugin-api';
-import { IconComponent, RouteRef, IdentityApi, SwappableComponentRef, AppTheme, TranslationResource, TranslationMessages } from '@backstage/frontend-plugin-api';
+import { IconComponent, IconElement, AppNode, RouteRef, IdentityApi, SwappableComponentRef, AppTheme, TranslationResource, TranslationMessages } from '@backstage/frontend-plugin-api';
 import { ReactNode, ComponentType } from 'react';
 
 /**
@@ -39,21 +39,68 @@ declare const AppRootWrapperBlueprint: _backstage_frontend_plugin_api.ExtensionB
 declare const IconBundleBlueprint: _backstage_frontend_plugin_api.ExtensionBlueprint<{
     kind: "icon-bundle";
     params: {
-        icons: { [key in string]: IconComponent; };
+        icons: { [key in string]: IconComponent | IconElement; };
     };
     output: _backstage_frontend_plugin_api.ExtensionDataRef<{
-        [x: string]: IconComponent;
+        [x: string]: IconComponent | IconElement;
     }, "core.icons", {}>;
     inputs: {};
     config: {};
     configInput: {};
     dataRefs: {
         icons: _backstage_frontend_plugin_api.ConfigurableExtensionDataRef<{
-            [x: string]: IconComponent;
+            [x: string]: IconComponent | IconElement;
         }, "core.icons", {}>;
     };
 }>;
 
+/**
+ * A navigation item auto-discovered from a page extension in the app.
+ *
+ * @public
+ */
+interface NavContentNavItem {
+    /** The app node of the page extension that this nav item points to */
+    node: AppNode;
+    /** The resolved route path */
+    href: string;
+    /** The display title */
+    title: string;
+    /** The display icon */
+    icon: IconElement;
+    /** The route ref of the source page */
+    routeRef: RouteRef;
+}
+/**
+ * A pre-bound renderer that wraps {@link NavContentNavItems} with a component,
+ * so that `take` and `rest` return rendered elements directly.
+ *
+ * @public
+ */
+interface NavContentNavItemsWithComponent {
+    /** Render and take a specific item by extension ID. Returns null if not found. */
+    take(id: string): JSX.Element | null;
+    /** Render all remaining items not yet taken, optionally sorted. */
+    rest(options?: {
+        sortBy?: 'title';
+    }): JSX.Element[];
+}
+/**
+ * A collection of nav items that supports picking specific items by ID
+ * and retrieving whatever remains. Created fresh for each render.
+ *
+ * @public
+ */
+interface NavContentNavItems {
+    /** Take an item by extension ID, removing it from the collection. */
+    take(id: string): NavContentNavItem | undefined;
+    /** All items not yet taken. */
+    rest(): NavContentNavItem[];
+    /** Create a copy of the collection preserving the current taken state. */
+    clone(): NavContentNavItems;
+    /** Create a renderer that wraps take/rest to return pre-rendered elements. */
+    withComponent(Component: ComponentType<NavContentNavItem>): NavContentNavItemsWithComponent;
+}
 /**
  * The props for the {@link NavContentComponent}.
  *
@@ -61,12 +108,15 @@ declare const IconBundleBlueprint: _backstage_frontend_plugin_api.ExtensionBluep
  */
 interface NavContentComponentProps {
     /**
-     * The nav items available to the component. These are all the items created
-     * with the {@link @backstage/frontend-plugin-api#NavItemBlueprint} in the app.
+     * Nav items auto-discovered from page extensions, with take/rest semantics
+     * for placing specific items in specific positions.
+     */
+    navItems: NavContentNavItems;
+    /**
+     * Flat list of nav items for simple rendering. Use `navItems` for more
+     * control over item placement.
      *
-     * In addition to the original properties from the nav items, these also
-     * include a resolved route path as `to`, and duplicated `title` as `text` to
-     * simplify rendering.
+     * @deprecated Use `navItems` instead.
      */
     items: Array<{
         icon: IconComponent;
@@ -238,4 +288,4 @@ declare const TranslationBlueprint: _backstage_frontend_plugin_api.ExtensionBlue
 }>;
 
 export { AppRootWrapperBlueprint, IconBundleBlueprint, NavContentBlueprint, RouterBlueprint, SignInPageBlueprint, SwappableComponentBlueprint, ThemeBlueprint, TranslationBlueprint };
-export type { NavContentComponent, NavContentComponentProps, SignInPageProps };
+export type { NavContentComponent, NavContentComponentProps, NavContentNavItem, NavContentNavItems, NavContentNavItemsWithComponent, SignInPageProps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-app-react",
-  "version": "0.1.1-next.0",
+  "version": "0.2.0",
   "description": "Web library for the app plugin",
   "backstage": {
     "role": "web-library",
@@ -39,26 +39,26 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/core-plugin-api": "1.12.2-next.0",
-    "@backstage/frontend-plugin-api": "0.14.0-next.0",
+    "@backstage/core-plugin-api": "^1.12.3",
+    "@backstage/frontend-plugin-api": "^0.14.0",
     "@material-ui/core": "^4.9.13"
   },
   "devDependencies": {
-    "@backstage/cli": "0.35.3-next.0",
-    "@backstage/frontend-test-utils": "0.4.5-next.0",
-    "@backstage/test-utils": "1.7.15-next.0",
+    "@backstage/cli": "^0.35.4",
+    "@backstage/frontend-test-utils": "^0.5.0",
+    "@backstage/test-utils": "^1.7.15",
     "@testing-library/jest-dom": "^6.0.0",
     "@testing-library/react": "^16.0.0",
     "@types/react": "^18.0.0",
     "react": "^18.0.2",
     "react-dom": "^18.0.2",
-    "react-router-dom": "^6.3.0"
+    "react-router-dom": "^6.30.2"
   },
   "peerDependencies": {
     "@types/react": "^17.0.0 || ^18.0.0",
     "react": "^17.0.0 || ^18.0.0",
     "react-dom": "^17.0.0 || ^18.0.0",
-    "react-router-dom": "^6.3.0"
+    "react-router-dom": "^6.30.2"
   },
   "peerDependenciesMeta": {
     "@types/react": {