Update Shell API's method signatures and enable typedoc integration

docusaurus/.gitignore

@@ -8,6 +8,9 @@
 .docusaurus
 .cache-loader
 
+# Typedoc integration
+docs/extensions/shell-api
+
 # Misc
 .DS_Store
 .env.local

docusaurus/docs/extensions/shell-api.md

@@ -0,0 +1,53 @@
+---
+id: shell-api
+---
+
+# Shell API
+
+> Available from Rancher `2.13` and onwards
+
+## What is the Shell API?
+
+The Shell API is a functional API that helps extension developers to interact with UI elements that are included in Rancher UI that are important for extension development. We have paid special attention on the implementation side of the architecture behind this API so that developers can use features such as Intellisense and auto-completion in your favourite IDE.
+
+![Intellisense](./screenshots/intellisense.png)
+
+## How to use the Shell API
+
+### Using Options API in Vue
+
+To use the Shell API in the context of the **Options API** of a Vue component, we globally expose the `$shell` property, which is available under the `this` object, such as:
+
+```ts
+import { NotificationLevel } from '@shell/types/notifications';
+
+this.$shell.notification.send(NotificationLevel.Success, 'Some notification title', 'Hello world! Success!', {})
+```
+
+### Using Composition API in Vue
+
+To use the Shell API in the context of the **Composition API** of a Vue component, we'll need to import the correct method to make the API available in the component:
+
+```ts
+import { useShell } from '@shell/apis';
+```
+
+then just assign to a constant in the context for your component and use it, such as:
+
+```ts
+import { NotificationLevel } from '@shell/types/notifications';
+
+const shellApi = useShell();
+
+// Example method to display a Growl message
+const sendNotification = () => shellApi.notification.send(NotificationLevel.Success, 'Some notification title', 'Hello world! Success!', {})
+```
+
+## Available API's
+
+| API | Description | Example |
+| :--- | :--- | :--- |
+| [Slide-In API](./shell-api/interfaces/SlideInApi) | Responsible for interacting with slide-in panels | <img src={require('/img/slidein.png').default} alt="slidein example" width="500" /> |
+| [Modal API](./shell-api/interfaces/ModalApi) | Responsible for interacting with modals | <img src={require('/img/modal.png').default} alt="modal example" width="500" /> |
+| [Notification API](./shell-api/interfaces/NotificationApi) | Responsible for interacting with the Rancher UI Notification Center | <img src={require('/img/notification.png').default} alt="notification example" width="500" /> |
+| [System API](./shell-api/interfaces/SystemApi) | API for system related information | <img src={require('/img/system.png').default} alt="system example" width="500" /> |

docusaurus/docusaurus.config.js

@@ -43,6 +43,53 @@ const config = {
   ],
 
   plugins: [
+    [
+      'docusaurus-plugin-typedoc',
+      {
+        // Set to true to hide the source path information entirely.
+        disableSources: true,
+
+        // This removes the prefix from the title of a generated page
+        // Ex: "Interface: ModalApi" vs "ModalApi"
+        textContentMappings: { 'title.memberPage': '{name}' },
+
+        // show params as code blocks
+        useCodeBlocks: true,
+
+        // The entry point for TypeDoc to start scanning for files.
+        // The path is relative to the `docusaurus` directory.
+        // entryPoints: ['../shell/apis/shell/*'],
+        entryPoints: ['../shell/apis/intf/shell.ts'],
+
+        // The tsconfig file for TypeDoc to use.
+        // This is CRITICAL to point to our special, isolated config
+        // to avoid the thousands of compilation errors from the main project.
+        tsconfig: 'tsconfig-typedoc-integration.json',
+
+        // The output directory for the generated markdown files.
+        // We are targeting the specific versioned folder for the "next" version
+        // and placing it directly into the "advanced" subfolder.
+        out: 'docs/extensions/shell-api',
+
+        // disables REAME as default entry point
+        readme: 'none',
+
+        // prevents deletion of files that are in "out" directory
+        cleanOutputDir: false,
+
+        // allows auto-generation of the sidebar for the auto-generated items
+        sidebar: { autoConfiguration: true },
+
+        // since we can't prevent the generation of a "bad" index file, we rename it to something harmless
+        entryFileName: '_api-index.md',
+
+        // A unique ID for this plugin instance. Needed so that it generates all the files successfully (including sidebar entries)
+        id: 'api-docs',
+
+        // exclude all code comments marked as @internal
+        excludeInternal: true
+      },
+    ],
     [require.resolve('docusaurus-lunr-search'), { excludeRoutes: ['internal/*', 'internal/**/*', '/internal/*', '/internal/**/*', 'blog/*', 'blog/**/*', '/blog/*', '/blog/**/*'] }
     ],
     [

docusaurus/extensionSidebar.js

@@ -1,3 +1,67 @@
+const fs = require('fs');
+const path = require('path');
+
+// Define the absolute path to the sidebar file that `docusaurus-plugin-typedoc` generates.
+const typedocSidebarPath = path.resolve(__dirname, './docs/extensions/shell-api/typedoc-sidebar.cjs');
+
+/**
+ * Recursively processes an array of Docusaurus sidebar items.
+ * It finds any 'doc' items and removes the incorrect 'extensions/' prefix
+ * from their ID, which is a known issue with the plugin in multi-instance setups.
+ *
+ * @param {Array<object>} items The array of sidebar items from the generated file.
+ * @returns {Array<object>} The corrected array of sidebar items.
+ */
+function fixTypedocIds(items) {
+  return items.map((item) => {
+    // 1. Start with a shallow copy of the item.
+    const newItem = { ...item };
+
+    // Remove 'extensions/' prefix from 'doc' IDs
+    if (newItem.type === 'doc' && newItem.id && newItem.id.startsWith('extensions/')) {
+      newItem.id = newItem.id.replace('extensions/', '');
+    }
+
+    // RECURSION: Process sub-items if it's a 'category'
+    if (newItem.type === 'category' && newItem.items) {
+      newItem.items = fixTypedocIds(newItem.items);
+    }
+
+    // Remove 'link' property if it points to an '_api-index' document (auto-generated by the plugin... we discard them)
+    const link = newItem.link;
+
+    if (
+      link &&
+      typeof link === 'object' && link !== null &&
+      link.id &&
+      typeof link.id === 'string' &&
+      link.id.endsWith('_api-index')
+    ) {
+      // Use object destructuring to create a new object without the 'link' property
+      // and return it immediately.
+      const { link: removedLink, ...rest } = newItem;
+
+      return rest;
+    }
+
+    // Return the (potentially) modified item.
+    return newItem;
+  });
+}
+
+// Initialize an empty array for the TypeDoc sidebar items.
+let typedocSidebarItems = [];
+
+// Safely check if the generated `typedoc-sidebar.cjs` file exists.
+// This prevents build errors if the file hasn't been generated yet.
+if (fs.existsSync(typedocSidebarPath)) {
+  // If the file exists, import its contents.
+  const originalTypedocSidebar = require(typedocSidebarPath);
+
+  // Run the imported items through our correction function.
+  typedocSidebarItems = fixTypedocIds(originalTypedocSidebar);
+}
+
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
   extensionsSidebar: [
@@ -51,6 +115,15 @@ const sidebars = {
               ],
             }],
         },
+        {
+          type:  'category',
+          label: 'Shell API',
+          link:  {
+            type: 'doc',
+            id:   'shell-api',
+          },
+          items: typedocSidebarItems
+        },
         {
           type:  'category',
           label: 'Extensions API',
@@ -123,7 +196,7 @@ const sidebars = {
             'advanced/stores',
             'advanced/version-compatibility',
             'advanced/safe-mode',
-            'advanced/yarn-link',
+            'advanced/yarn-link'
           ]
         },
         'publishing',

docusaurus/package.json

@@ -24,11 +24,17 @@
     "prism-react-renderer": "^2.1.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "yaml": "2.5.1"
+    "yaml": "2.5.1",
+    "docusaurus-plugin-typedoc": "^1.4.2",
+    "typedoc": "^0.28.13",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "^5.9.2"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "^3.6.3",
-    "@docusaurus/types": "3.0.0"
+    "@docusaurus/types": "3.0.0",
+    "vue": "3.5.18",
+    "vue-router": "4.5.1"
   },
   "browserslist": {
     "production": [

docusaurus/src/css/custom.css

@@ -176,6 +176,19 @@ a.gettingStartedLink .resourcesSvg svg {
 hr {
   margin: 2rem 0;
 }
+
+/* Fixes for CSS issues with auto generated docs */
+/* Fixes anchor styling methods subtitle */
+h4.anchor {
+  font-size: 26px;
+}
+
+/* Fixes anchor styling for method params */
+h5.anchor {
+  font-size: 20px;
+  text-decoration: underline;
+}
+
 @media screen and (max-width: 996px) {
   .homepage-banner {
     padding: 30px 30px;

docusaurus/tsconfig-typedoc-integration.json

@@ -0,0 +1,16 @@
+{
+    "extends": "./tsconfig.paths.json",
+    "compilerOptions": {
+        "baseUrl": ".",
+        "module": "commonjs",
+        "target": "es6",
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+    },
+    "include": [
+        "../shell/apis/intf/shell.ts"
+    ],
+    "exclude": [
+        "node_modules"
+    ]
+}

docusaurus/tsconfig.paths.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "paths": {
+      // we need to explicitly tell docusaurus where to look for vue types...
+      "vue": [
+        "node_modules/vue"
+      ],
+      "vue-router": [
+        "node_modules/vue-router"
+      ],
+      "~/*": [
+        "../*"
+      ],
+      "@/*": [
+        "../*"
+      ],
+      "@shell/*": [
+        "../shell/*"
+      ],
+      "@pkg/*": [
+        "../shell/pkg/*"
+      ],
+      "@components/*": [
+        "../pkg/rancher-components/src/components/*"
+      ]
+    }
+  }
+}

pkg/rancher-prime/tsconfig.json

@@ -46,7 +46,8 @@
     "**/*.ts",
     "**/*.d.ts",
     "**/*.tsx",
-    "**/*.vue"
+    "**/*.vue",
+    "../../shell/types/vue-shim.d.ts"
   ],
   "exclude": [
     "../../node_modules"

shell/apis/impl/apis.ts

@@ -0,0 +1,61 @@
+import { throttle } from 'lodash';
+import { createExtensionManager } from '@shell/core/extension-manager-impl';
+import { ShellApiImpl } from '@shell/apis/shell';
+
+/**
+ * Initialise the APIs that are available in the shell
+ *
+ * This is loaded during app startiup in `initialize/index.js`
+ */
+export function initUiApis(context: any, inject: any, vueApp: any) {
+  // ======================================================================================================================
+  // Extension Manager
+  // ======================================================================================================================
+  const extensionManager = createExtensionManager(context);
+  const deprecationMessage = '[DEPRECATED] `this.$plugin` is deprecated and will be removed in a future version. Use `this.$extension` instead.';
+
+  registerApi('plugin', deprecationProxy(extensionManager, deprecationMessage), inject, vueApp);
+  registerApi('extension', extensionManager, inject, vueApp);
+
+  // ======================================================================================================================
+  // Shell API
+  // ======================================================================================================================
+  registerApi('shell', new ShellApiImpl(context.store), inject, vueApp);
+}
+
+// ======================================================================================================================
+// Helpers
+// ======================================================================================================================
+
+function registerApi(name: string, api: any, inject: any, vueApp: any) {
+  inject(name, api);
+  vueApp.provide(`$${ name }`, api);
+}
+
+/**
+ * Proxy to log a deprecation warning when target is accessed. Only prints
+ * deprecation warnings in dev builds.
+ * @param {*} target the object to proxy
+ * @param {*} message the deprecation warning to print to the console
+ * @returns The proxied target that prints a deprecation warning when target is
+ * accessed
+ */
+const deprecationProxy = (target: any, message: string) => {
+  const logWarning = throttle(() => {
+    // eslint-disable-next-line no-console
+    console.warn(message);
+  }, 150);
+
+  const deprecationHandler = {
+    get(target: any, prop: any) {
+      logWarning();
+
+      return Reflect.get(target, prop);
+    }
+  };
+
+  // an empty handler allows the proxy to behave just like the original target
+  const proxyHandler = !!process.env.dev ? deprecationHandler : {};
+
+  return new Proxy(target, proxyHandler);
+};