@rancher/shell 3.0.8-rc.12 → 3.0.8-rc.13

package/types/notifications/index.ts

@@ -4,36 +4,102 @@ import { RouteLocationRaw } from 'vue-router';
  * Type definitions for the Notification Center
  */
 
-/**
- * Notification Level for a notification in the Notification Center
- */
 export enum NotificationLevel {
+  /**
+   * An announcement. To be used when we want to inform on high-interest topics - news, updates, changes, scheduled maintenance, etc. E.g. “New version available!” <img class="svg-blue" src="https://raw.githubusercontent.com/rancher/icons/refs/heads/master/svg/notify-announcement.svg" width="20" />
+   */
   Announcement = 0, // eslint-disable-line no-unused-vars
+  /**
+   * A task that is underway. To be used when we want to inform on a process taking place - on-going actions that might take a while. E.g. “Cluster provisioning in progress”. The progress bar will also be shown if the `progress` field is set <img class="svg-blue" src="https://raw.githubusercontent.com/rancher/icons/refs/heads/master/svg/notify-busy.svg" width="20" />
+   */
   Task, // eslint-disable-line no-unused-vars
+  /**
+   * Information notification. To be used when we want to inform on low-interest topics. E.g. “Welcome to Rancher v2.8" <img class="svg-blue" src="https://raw.githubusercontent.com/rancher/icons/refs/heads/master/svg/notify-info.svg"/>
+   */
   Info, // eslint-disable-line no-unused-vars
+  /**
+   * Notification that something has completed successfully. To be used when we want to confirm a successful action was completed. E.g. “Cluster provisioning completed” <img class="svg-green" src="https://raw.githubusercontent.com/rancher/icons/refs/heads/master/svg/notify-tick.svg"/>
+   */
   Success, // eslint-disable-line no-unused-vars
+  /**
+   * Notification of a warning. To be used when we want to warn about a potential risk. E.g. “Nodes limitation warning” <img class="svg-orange" src="https://raw.githubusercontent.com/rancher/icons/refs/heads/master/svg/notify-warning.svg"/>
+   */
   Warning, // eslint-disable-line no-unused-vars
+  /**
+   * Notification of an error. To be used when we want to alert on a confirmed risk. E.g. “Extension failed to load” <img class="svg-red" src="https://raw.githubusercontent.com/rancher/icons/refs/heads/master/svg/notify-error.svg"/>
+   */
   Error, // eslint-disable-line no-unused-vars
   Hidden, // eslint-disable-line no-unused-vars
 }
 
 /**
- * An action that is shown as a button in the Notification Center
+ * Notification Action definition
  */
-export type NotificationAction = {
-  label: string; // Button label for the action
-  target?: string; // HREF target when the button is clicked
-  route?: RouteLocationRaw; // Route to navigate to when the button is clicked
-};
+export interface NotificationAction {
+  /**
+   * Button label for the action
+   */
+  label: string;
+  /**
+   * Href target when the button is clicked
+   */
+  target?: string;
+  /**
+   * Vue Route to navigate to when the button is clicked
+   */
+  route?: RouteLocationRaw;
+}
 
 /**
- * Defines the User Preference linked to a notification
+ * Notification Preference definition
  */
-export type NotificationPreference = {
-  key: string; // User preference key to use when setting the preference when the notification is marked as read/unread
-  value: string; // User preference value to use when setting the preference when the notification is marked as read
-  unsetValue?: string; // User preference value to use when setting the preference when the notification is marked as unread - defaults to empty string
-};
+export interface NotificationPreference {
+  /**
+   * User preference key to use when setting the preference when the notification is marked as read
+   */
+  key: string;
+  /**
+   * User preference value to use when setting the preference when the notification is marked as read
+   */
+  value: string;
+  /**
+   * User preference value to use when setting the preference when the notification is marked as unread - defaults to empty string
+   */
+  unsetValue?: string;
+}
+
+/**
+ * Configuration object for the Notification Center
+ *
+ */
+export interface NotificationConfig {
+  /**
+   * - **{@link NotificationAction}**
+   *
+   * Primary action to be shown in the notification
+   */
+  primaryAction?: NotificationAction;
+  /**
+   * - **{@link NotificationAction}**
+   *
+   * Secondary to be shown in the notification
+   */
+  secondaryAction?: NotificationAction;
+  /**
+   * Unique ID for the notification
+   */
+  id?: string;
+  /**
+   * Progress (0-100) for notifications of type `Task`
+   */
+  progress?: number;
+  /**
+   * - **{@link NotificationPreference}**
+   *
+   * User Preference tied to the notification (the preference will be updated when the notification is marked read)
+   */
+  preference?: NotificationPreference;
+}
 
 /**
  * Type for Encrypted Notification data that is stored in local storage
@@ -96,3 +162,48 @@ export interface NotificationHandler {
    */
   onReadUpdated(notification: Notification, read: boolean): void;
 }
+
+/**
+ * API for notifications in the Rancher UI Notification Center
+ * * ![notification Example](/img/notification.png)
+ */
+export interface NotificationApi {
+  /**
+   * Sends a notification to the Rancher UI Notification Center
+   *
+   * Example:
+   * ```ts
+   * import { NotificationLevel } from '@shell/types/notifications';
+   *
+   * this.$shell.notification.send(NotificationLevel.Success, 'Some notification title', 'Hello world! Success!', {})
+   * ```
+   *
+   * For usage with the Composition API check usage guide [here](../../shell-api#using-composition-api-in-vue).
+   *
+   * @param level The `level` specifies the importance of the notification and determines the icon that is shown in the notification
+   * @param title The notification title
+   * @param message The notification message to be displayed
+   * @param config Notifications configuration object
+   *
+   * @returns notification ID
+   *
+   */
+  send(level: NotificationLevel | NotificationLevel, title: string, message?:string, config?: NotificationConfig): Promise<string>;
+
+  /**
+   * Update notification progress (Only valid for notifications of type `Task`)
+   *
+   * Example:
+   * ```ts
+   * this.$shell.notification.updateProgress('some-notification-id', 80)
+   * ```
+   *
+   * For usage with the Composition API check usage guide [here](../../shell-api#using-composition-api-in-vue).
+   *
+   * @param notificationId Unique ID for the notification
+   * @param progress Progress (0-100) for notifications of type `Task`
+   *
+   */
+
+  updateProgress(notificationId: string, progress: number): void;
+}

package/types/rancher/index.d.ts

@@ -8,3 +8,12 @@ declare module '@shell/store/type-map' {
 }
 
 declare module '@shell/plugins/dashboard-store';
+
+declare module '@shell/config/query-params' {
+  export const _DETAIL: string;
+}
+
+declare module '@shell/config/version' {
+  export const CURRENT_RANCHER_VERSION: string;
+  export function getVersionData(): any;
+}

package/types/vue-shim.d.ts

@@ -1,7 +1,9 @@
 /* eslint-disable */
-import type ShellApi from '@shell/plugins/internal-api/shell/shell.api';
 import { VuexStore } from '@shell/types/store/vuex';
 
+// Include the types for the APIs
+/// <reference path="../apis/vue-shim.d.ts" />
+
 export {};
 
 declare module 'vue' {
@@ -14,7 +16,6 @@ declare module 'vue' {
       (key: string, args?: Record<string, any>, raw?: boolean): string;
       (options: { k: string; raw?: boolean; tag?: string | Record<string, any>; escapehtml?: boolean }): string;
     },
-    $store: VuexStore,
-    $shell: ShellApi,
+    $store: VuexStore
   }
-}
+}

package/composables/useExtensionManager.ts

@@ -1,17 +0,0 @@
-import { ExtensionManager } from '@shell/types/extension-manager';
-import { getExtensionManager } from '@shell/core/extension-manager-impl';
-
-/**
- * Provides access to the registered extension manager instance. Used within Vue
- * components or other composables that require extension functionality.
- * @returns The extension manager instance
- */
-export const useExtensionManager = (): ExtensionManager => {
-  const extension = getExtensionManager();
-
-  if (!extension) {
-    throw new Error('useExtensionManager must be called after the extensionManager has been initialized');
-  }
-
-  return extension;
-};

package/core/__test__/extension-manager-impl.test.js

@@ -1,236 +0,0 @@
-import { DEVELOPER_LOAD_NAME_SUFFIX } from '@shell/core/extension-manager-impl';
-
-// Mock external dependencies
-jest.mock('@shell/store/type-map', () => ({ productsLoaded: jest.fn().mockReturnValue(true) }));
-
-jest.mock('@shell/plugins/dashboard-store/model-loader', () => ({ clearModelCache: jest.fn() }));
-
-jest.mock('@shell/config/uiplugins', () => ({ UI_PLUGIN_BASE_URL: '/api/v1/uiplugins' }));
-
-jest.mock('@shell/plugins/clean-html', () => ({
-  addLinkInterceptor:    jest.fn(),
-  removeLinkInterceptor: jest.fn(),
-}));
-
-// Mock the Plugin class
-jest.mock('@shell/core/plugin', () => {
-  return {
-    Plugin: jest.fn().mockImplementation((id) => ({
-      id,
-      name:            id,
-      types:           {},
-      uiConfig:        {},
-      l10n:            {},
-      modelExtensions: {},
-      stores:          [],
-      locales:         [],
-      routes:          [],
-      validators:      {},
-      uninstallHooks:  [],
-      productNames:    [],
-    })),
-    EXT_IDS: {
-      MODELS:          'models',
-      MODEL_EXTENSION: 'model-extension'
-    },
-    ExtensionPoint: { EDIT_YAML: 'edit-yaml' }
-  };
-});
-
-// Mock PluginRoutes
-jest.mock('@shell/core/plugin-routes', () => {
-  return { PluginRoutes: jest.fn().mockImplementation(() => ({ addRoutes: jest.fn() })) };
-});
-
-describe('extension Manager', () => {
-  let mockStore;
-  let mockApp;
-  let context;
-
-  // These variables will be assigned the fresh functions inside beforeEach
-  let initExtensionManager;
-  let getExtensionManager;
-
-  beforeEach(() => {
-    // singleton instance for every test run, preventing mock store leaks.
-    jest.resetModules();
-
-    // Re-require the System Under Test (SUT)
-    const extensionManagerModule = require('../extension-manager-impl');
-
-    initExtensionManager = extensionManagerModule.initExtensionManager;
-    getExtensionManager = extensionManagerModule.getExtensionManager;
-
-    jest.clearAllMocks();
-
-    // Setup Mock Context
-    mockStore = {
-      getters:  { 'i18n/t': jest.fn() },
-      dispatch: jest.fn(),
-      commit:   jest.fn(),
-    };
-
-    mockApp = { router: {} };
-
-    context = {
-      app:      mockApp,
-      store:    mockStore,
-      $axios:   {},
-      redirect: jest.fn(),
-    };
-
-    // Clean up DOM from previous tests
-    document.head.innerHTML = '';
-  });
-
-  describe('singleton Pattern', () => {
-    it('initializes and returns the same instance', () => {
-      const instance1 = initExtensionManager(context);
-      const instance2 = getExtensionManager();
-      const instance3 = initExtensionManager(context);
-
-      expect(instance1).toBeDefined();
-      expect(instance1).toBe(instance2);
-      expect(instance1).toBe(instance3);
-    });
-  });
-
-  describe('registration (Dynamic)', () => {
-    it('registers and retrieves a dynamic component', () => {
-      const manager = initExtensionManager(context);
-      const mockFn = jest.fn();
-
-      manager.register('component', 'my-component', mockFn);
-
-      const retrieved = manager.getDynamic('component', 'my-component');
-
-      expect(retrieved).toBe(mockFn);
-    });
-
-    it('unregisters a dynamic component', () => {
-      const manager = initExtensionManager(context);
-      const mockFn = jest.fn();
-
-      manager.register('component', 'my-component', mockFn);
-      manager.unregister('component', 'my-component');
-
-      const retrieved = manager.getDynamic('component', 'my-component');
-
-      expect(retrieved).toBeUndefined();
-    });
-  });
-
-  describe('loadPluginAsync (URL Generation)', () => {
-    let manager;
-
-    beforeEach(() => {
-      manager = initExtensionManager(context);
-      // Mock the internal loadAsync so we only test URL generation here
-      jest.spyOn(manager, 'loadAsync').mockImplementation().mockResolvedValue();
-    });
-
-    it('generates correct URL for standard plugin', async() => {
-      const pluginData = { name: 'elemental', version: '1.0.0' };
-      const expectedId = 'elemental-1.0.0';
-      const expectedUrl = `/api/v1/uiplugins/elemental/1.0.0/plugin/elemental-1.0.0.umd.min.js`;
-
-      await manager.loadPluginAsync(pluginData);
-
-      expect(manager.loadAsync).toHaveBeenCalledWith(expectedId, expectedUrl);
-    });
-
-    it('handles "direct" metadata plugins', async() => {
-      const pluginData = {
-        name:     'direct-plugin',
-        version:  '1.0.0',
-        endpoint: 'http://localhost:8000/plugin.js',
-        metadata: { direct: 'true' }
-      };
-
-      await manager.loadPluginAsync(pluginData);
-
-      expect(manager.loadAsync).toHaveBeenCalledWith('direct-plugin-1.0.0', 'http://localhost:8000/plugin.js');
-    });
-
-    it('removes developer suffix from ID but keeps it for internal logic', async() => {
-      const pluginData = {
-        name:    `my-plugin${ DEVELOPER_LOAD_NAME_SUFFIX }`,
-        version: `1.0.0`
-      };
-
-      await manager.loadPluginAsync(pluginData);
-
-      // Expected ID passed to loadAsync should NOT have the suffix
-      const expectedIdWithoutSuffix = 'my-plugin-1.0.0';
-
-      expect(manager.loadAsync).toHaveBeenCalledWith(
-        expectedIdWithoutSuffix,
-        expect.any(String)
-      );
-    });
-  });
-
-  describe('loadAsync (Script Injection)', () => {
-    let manager;
-
-    beforeEach(() => {
-      manager = initExtensionManager(context);
-    });
-
-    it('resolves immediately if element already exists', async() => {
-      const id = 'existing-plugin';
-      const script = document.createElement('script');
-
-      script.id = id;
-      document.body.appendChild(script);
-
-      await expect(manager.loadAsync(id, 'url.js')).resolves.toBeUndefined();
-
-      document.body.removeChild(script);
-    });
-
-    it('injects script tag and initializes plugin on load', async() => {
-      const pluginId = 'test-plugin';
-      const pluginUrl = 'http://test.com/plugin.js';
-
-      // Mock the window object to simulate the plugin loading into global scope
-      const mockPluginInit = jest.fn();
-
-      window[pluginId] = { default: mockPluginInit };
-
-      // Start the load
-      const loadPromise = manager.loadAsync(pluginId, pluginUrl);
-
-      // Find the injected script tag in the DOM
-      const script = document.head.querySelector(`script[id="${ pluginId }"]`);
-
-      expect(script).toBeTruthy();
-      expect(script.src).toBe(pluginUrl);
-
-      // Manually trigger the onload event
-      script.onload();
-
-      // Await the promise
-      await loadPromise;
-
-      // Assertions
-      expect(mockPluginInit).toHaveBeenCalledWith(expect.objectContaining({ id: pluginId }), expect.objectContaining({ ...context }));
-      expect(mockStore.dispatch).toHaveBeenCalledWith('uiplugins/addPlugin', expect.objectContaining({ id: pluginId }));
-
-      // Cleanup
-      delete window[pluginId];
-    });
-
-    it('rejects if script load fails', async() => {
-      const pluginId = 'fail-plugin';
-      const loadPromise = manager.loadAsync(pluginId, 'bad-url.js');
-
-      const script = document.head.querySelector(`script[id="${ pluginId }"]`);
-
-      // Trigger error
-      script.onerror({ target: { src: 'bad-url.js' } });
-
-      await expect(loadPromise).rejects.toThrow('Failed to load script');
-    });
-  });
-});

package/core/plugins.js

@@ -1,38 +0,0 @@
-import { throttle } from 'lodash';
-import { initExtensionManager } from './extension-manager-impl';
-
-export default function(context, inject) {
-  const extensionManager = initExtensionManager(context);
-  const deprecationMessage = '[DEPRECATED] `this.$plugin` is deprecated and will be removed in a future version. Use `this.$extension` instead.';
-
-  inject('plugin', deprecationProxy(extensionManager, deprecationMessage));
-  inject('extension', extensionManager);
-}
-
-/**
- * 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, message) => {
-  const logWarning = throttle(() => {
-    // eslint-disable-next-line no-console
-    console.warn(message);
-  }, 150);
-
-  const deprecationHandler = {
-    get(target, prop) {
-      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);
-};

package/plugins/internal-api/index.ts

@@ -1,37 +0,0 @@
-import { Store } from 'vuex';
-
-interface PluginContext {
-  store: Store<any>;
-  [key: string]: any;
-}
-
-export default function(context: PluginContext, inject: (key: string, value: any) => void) {
-  const { store } = context;
-
-  // Load all API modules
-  const apiContext = (require as any).context(
-    '@shell/plugins/internal-api', // the base directory
-    true, // whether to search subdirectories
-    /\.api\.ts$/ // only .api.ts files
-  );
-
-  apiContext.keys().forEach((relativePath: string) => {
-    const mod = apiContext(relativePath);
-    const ApiClass = mod.default;
-
-    if (typeof ApiClass === 'function') {
-      // Check for a static `apiName` property, or fallback to filename
-      let apiName: string = ApiClass.apiName();
-
-      if (!apiName) {
-        // fallback to filename (strip leading ‘./’ and extension)
-        apiName = `$${ relativePath.replace(/^\.\//, '').replace(/\.\w+$/, '') }`;
-      }
-
-      const instance = new ApiClass(store);
-
-      // The inject() method automatically adds the `$` prefix
-      inject(apiName, instance);
-    }
-  });
-}

package/plugins/internal-api/shared/base-api.ts

@@ -1,13 +0,0 @@
-export abstract class BaseApi {
-  // The Vuex store, available to all API classes
-  protected $store: any;
-
-  // Documented requirement: each API should define its static apiName.
-  static apiName(): string {
-    throw new Error('apiName() static method has not been implemented');
-  }
-
-  constructor(store: any) {
-    this.$store = store;
-  }
-}

package/plugins/internal-api/shell/shell.api.ts

@@ -1,108 +0,0 @@
-import { GrowlConfig } from '@shell/types/internal-api/shell/growl';
-import { ModalConfig } from '@shell/types/internal-api/shell/modal';
-import { SlideInConfig } from '@shell/types/internal-api/shell/slideIn';
-
-import { BaseApi } from '@shell/plugins/internal-api/shared/base-api';
-
-export default class ShellApi extends BaseApi {
-  static apiName() {
-    return 'shell';
-  }
-
-  /**
-   * Dispatches a growl notification.
-   *
-   * @param config - Configuration for the growl notification.
-   * - If `message` is a string, it is treated as the main content of the notification.
-   * - If `message` is a `DetailedMessage` object, `title` and `description` are extracted.
-   *
-   * Example:
-   * ```ts
-   * this.$shell.growl({ message: 'Operation successful!', type: 'success' });
-   * this.$shell.growl({ message: { title: 'Warning', description: 'Check your input.' }, type: 'warning' });
-   * ```
-   */
-  protected growl(config: GrowlConfig): void {
-    const { type = 'error', timeout = 5000 } = config;
-
-    let title = '';
-    let description = '';
-
-    if (typeof config.message === 'string') {
-      description = config.message;
-    } else {
-      title = config.message.title || '';
-      description = config.message.description;
-    }
-
-    this.$store.dispatch(
-      `growl/${ type }`,
-      {
-        title,
-        message: description,
-        timeout,
-      },
-      { root: true }
-    );
-  }
-
-  /**
-   * Opens a modal by committing to the Vuex store.
-   *
-   * This method updates the store's `modal` module to show a modal with the
-   * specified configuration. The modal is rendered using the `ModalManager` component,
-   * and its content is dynamically loaded based on the `component` field in the configuration.
-   *
-   * @param config A `ModalConfig` object defining the modal’s content and behavior.
-   *
-   * Example:
-   * ```ts
-   * this.$shell.modal({
-   *   component: MyCustomModal,
-   *   componentProps: { title: 'Hello Modal' },
-   *   resources: [someResource],
-   *   modalWidth: '800px',
-   *   closeOnClickOutside: false
-   * });
-   * ```
-   */
-  protected modal(config: ModalConfig): void {
-    this.$store.commit('modal/openModal', {
-      component:           config.component,
-      componentProps:      config.componentProps || {},
-      resources:           config.resources || [],
-      modalWidth:          config.modalWidth || '600px',
-      closeOnClickOutside: config.closeOnClickOutside ?? true,
-      // modalSticky:         config.modalSticky ?? false // Not implemented yet
-    });
-  }
-
-  /**
-   * Opens the slide-in panel with the specified component and props.
-   *
-   * This method commits the `open` mutation to the `slideInPanel` Vuex module,
-   * which sets the current component to be rendered and its associated props.
-   * The slide-in panel becomes visible after the mutation.
-   *
-   * @param config - The configuration object for the slide-in panel.
-   *
-   * Example Usage:
-   * ```ts
-   * import MyComponent from '@/components/MyComponent.vue';
-   *
-   * this.$shell.slideInPanel({
-   *   component: MyComponent,
-   *   componentProps: { foo: 'bar' }
-   * });
-   * ```
-   *
-   * @param config.component - A Vue component (imported SFC, functional component, etc.) to be rendered in the panel.
-   * @param config.componentProps - (Optional) Props to pass to the component. These should align with the component's defined props.
-   */
-  protected slideInPanel(config: SlideInConfig): void {
-    this.$store.commit('slideInPanel/open', {
-      component:      config.component,
-      componentProps: config.componentProps || {}
-    });
-  }
-}

package/types/internal-api/shell/growl.d.ts

@@ -1,25 +0,0 @@
-export interface DetailedMessage {
-  title?: string;
-  description: string;
-}
-
-export interface GrowlConfig {
-  /**
-   * The content of the notification message.
-   * Either a simple string or an object with `title` and `description` for detailed notifications.
-   */
-  message: string | DetailedMessage;
-
-  /**
-   * Optional type of the growl notification.
-   * Determines the visual style of the notification.
-   * Defaults to `'error'` if not provided.
-   */
-  type?: 'success' | 'info' | 'warning' | 'error';
-
-  /**
-   * Optional duration (in milliseconds) for which the notification should be displayed.
-   * Defaults to `5000` milliseconds. A value of `0` keeps the notification indefinitely.
-   */
-  timeout?: number;
-}