@rancher/shell 3.0.8-rc.8 → 3.0.8

package/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);
+};

package/apis/index.ts

@@ -0,0 +1,40 @@
+// Main export for APIs, particularly for the composition API
+
+import { inject } from 'vue';
+import { ExtensionManager } from '@shell/types/extension-manager';
+import { ShellApi as ShellApiImport } from '@shell/apis/intf/shell';
+
+// Re-export the types for the APIs, so they appear in this module
+export type ShellApi = ShellApiImport;
+export type ExtensionManagerApi = ExtensionManager;
+
+/**
+ * Returns an object that can be used to access the registered extension manager instance.
+ *
+ * @returns Returns an object that can be used to access the registered extension manager instance.
+ */
+export const useExtensionManager = (): ExtensionManagerApi => {
+  return getApi<ExtensionManagerApi>('$extension', 'useExtensionManager');
+};
+
+/**
+ * Returns an object that implements the ShellApi interface
+ *
+ * @returns Returns an object that implements the ShellApi interface
+ */
+export const useShell = (): ShellApi => {
+  return getApi<ShellApi>('$shell', 'useShell');
+};
+
+// =================================================================================================================
+// Internal helper to get any API by key with error handling
+// =================================================================================================================
+function getApi<T>(key: string, name: string): T {
+  const api = inject<T>(key);
+
+  if (!api) {
+    throw new Error(`${ name } must only be called after ${ key } has been initialized`);
+  }
+
+  return api as T;
+}

package/apis/intf/modal.ts

@@ -0,0 +1,90 @@
+import { Component } from 'vue';
+
+/**
+ * Configuration object for opening a modal.
+ */
+export interface ModalConfig {
+  /**
+   * Props to pass directly to the component rendered inside the modal.
+   *
+   * Example:
+   * ```ts
+   * props: { title: 'Hello Modal', isVisible: true }
+   * ```
+   */
+  props?: Record<string, any>;
+
+  /**
+   * Array of resources that the modal component might need.
+   * These are passed directly into the modal's `resources` prop.
+   *
+   * Example:
+   * ```ts
+   * resources: [myResource, anotherResource]
+   * ```
+   */
+  resources?: any[];
+
+  /**
+   * Custom width for the modal. Defaults to `600px`.
+   * The width can be specified as a string with a valid unit (`px`, `%`, `rem`, etc.).
+   *
+   * Examples:
+   * ```ts
+   * width: '800px' // Width in pixels
+   * width: '75%'   // Width as a percentage
+   * ```
+   */
+  width?: string;
+
+  /**
+   * Determines if clicking outside the modal will close it. Defaults to `true`.
+   * Set this to `false` to prevent closing via outside clicks.
+   *
+   * Example:
+   * ```ts
+   * closeOnClickOutside: false
+   * ```
+   */
+  closeOnClickOutside?: boolean;
+
+  /**
+   * If true, the modal is considered "sticky" and may not close automatically
+   * on certain user interactions. Defaults to `false`.
+   *
+   * Example:
+   * ```ts
+   * modalSticky: true
+   * ```
+   */
+  // modalSticky?: boolean; // Not implemented yet
+}
+
+/**
+ * API for displaying modals in Rancher UI. Here's what a Modal looks like in Rancher UI:
+ * * ![modal Example](/img/modal.png)
+ */
+export interface ModalApi {
+  /**
+   * Opens a modal dialog in Rancher UI
+   *
+   * Example:
+   * ```ts
+   * import MyCustomModal from '@/components/MyCustomModal.vue';
+   *
+   * this.$shell.modal.open(MyCustomModal, {
+   *   props: { title: 'Hello Modal' }
+   * });
+   * ```
+   * For usage with the Composition API check usage guide [here](../../shell-api#using-composition-api-in-vue).
+   *
+   * @param component
+   * The Vue component to be displayed inside the modal.
+   * This can be any SFC (Single-File Component) imported and passed in as a `Component`.
+   *
+   *
+   * @param config Modal configuration object
+   *
+   */
+  open(component: Component, config?: ModalConfig): void;
+}

package/apis/intf/shell.ts

@@ -0,0 +1,36 @@
+
+import { NotificationApi } from '@shell/types/notifications';
+import { ModalApi } from '@shell/apis/intf/modal';
+import { SlideInApi } from '@shell/apis/intf/slide-in';
+import { SystemApi } from '@shell/apis/intf/system';
+
+export * from '@shell/types/notifications';
+export * from '@shell/apis/intf/modal';
+export * from '@shell/apis/intf/slide-in';
+export * from '@shell/apis/intf/system';
+
+/**
+ * @internal
+ * Available "API's" inside Shell API
+ */
+export interface ShellApi {
+  /**
+   * Provides access to the Modal API which can be used for displaying modals in Rancher UI
+   */
+  get modal(): ModalApi;
+
+  /**
+   * Provides access to the Slide-In API which can be used for displaying Slide-In panels in Rancher UI
+   */
+  get slideIn(): SlideInApi;
+
+  /**
+   * Provides access to the Notification Center API which can be used for notifications in the Rancher UI Notification Center
+   */
+  get notification(): NotificationApi;
+
+  /**
+   * Provides access to the system API which providers information about the current system
+   */
+  get system(): SystemApi;
+}

package/apis/intf/slide-in.ts

@@ -0,0 +1,98 @@
+import { Component } from 'vue';
+
+/**
+ *
+ * Configuration object for opening a Slide-In panel. Here's what a Slide-In looks like in Rancher UI:
+ *
+ */
+export interface SlideInConfig {
+  /**
+   *
+   * Width of the Slide-In panel in percentage, related to the window width. Defaults to `33%`
+   *
+   */
+  width?: string;
+  /**
+   *
+   * Height of the Slide-In panel. Can be percentage or vh. Defaults to (window - header) height.
+   * Can be set as `33%` or `80vh`
+   *
+   */
+  height?: string;
+  /**
+   *
+   * CSS Top position for the Slide-In panel, string using px, as `0px` or `20px`. Default is right below header height
+   *
+   */
+  top?: string;
+  /**
+   *
+   * title for the Slide-In panel
+   *
+   */
+  title?: string;
+  /**
+   *
+   * Wether Slide-In header is displayed or not
+   *
+   */
+  showHeader?: boolean;
+  /**
+   *
+   * Array of props to watch out for in route, when they change, closes Slide-In
+   * @ignore
+   *
+   */
+  closeOnRouteChange?: [string];
+  /**
+   *
+   * Return focus selector for focus trap
+   * @ignore
+   *
+   */
+  returnFocusSelector?: string;
+  /**
+   *
+   * We can pass variable (value) to "force" focus trap to initialize "on-demand"
+   * @ignore
+   *
+   */
+  focusTrapWatcherBasedVariable?: boolean;
+  /**
+   *
+   * Vue Props to pass directly to the component rendered inside the slide in panel in an object format as "props=..."
+   *
+   * Useful for passing additional information or context to the component rendered inside the Slide-In window
+   *
+   */
+  [key: string]: any;
+}
+
+/**
+ * API for displaying Slide-In panels in Rancher UI
+ * * ![slidein Example](/img/slidein.png)
+ */
+export interface SlideInApi {
+  /**
+   * Opens a slide in panel in Rancher UI
+   *
+   * Example:
+   * ```ts
+   * import MyCustomSlideIn from '@/components/MyCustomSlideIn.vue';
+   *
+   * this.$shell.slideIn.open(MyCustomSlideIn, {
+   *   title: 'Hello from SlideIn panel!'
+   * });
+   * ```
+   *
+   * For usage with the Composition API check usage guide [here](../../shell-api#using-composition-api-in-vue).
+   *
+   * @param component
+   * The Vue component to be displayed inside the slide in panel.
+   * This can be any SFC (Single-File Component) imported and passed in as a `Component`.
+   *
+   * @param config Slide-In configuration object
+   *
+   */
+  open(component: Component, config?: SlideInConfig): void;
+}

package/apis/intf/system.ts

@@ -0,0 +1,41 @@
+/**
+ * system API which providers information about the current system
+ * * ![system Example](/img/system.png)
+ *
+ * Usage example:
+ * ```ts
+ * const rancherVersion = this.$shell.system.rancherVersion;
+ * console.log('Rancher Version:', rancherVersion);
+ * ```
+ *
+ */
+export interface SystemApi {
+  /**
+   * Rancher version
+   */
+  rancherVersion: string;
+  /**
+   * Rancher UI version
+   */
+  uiVersion: string;
+  /**
+   * If Rancher system running is Prime
+   */
+  isRancherPrime: boolean;
+  /**
+   * Git Commit for Rancher system running
+   */
+  gitCommit: string;
+  /**
+   * Rancher Kubernetes version
+   */
+  kubernetesVersion: string;
+  /**
+   * If Rancher system is a Dev build
+   */
+  isDevBuild: boolean;
+  /**
+   * If Rancher system is a Pre-Release build/version
+   */
+  isPrereleaseVersion: boolean;
+}

package/apis/shell/__tests__/modal.test.ts

@@ -0,0 +1,80 @@
+// modal.test.ts
+
+import {
+  describe, it, expect, jest, beforeEach
+} from '@jest/globals';
+import { ModalApiImpl } from '../modal'; // Adjust path as needed
+import { Store } from 'vuex';
+
+// A mock component to use in tests
+const MockComponent = { template: '<div>Mock</div>' };
+
+describe('modalApiImpl', () => {
+  let mockStore: Store<any>;
+  let modalApi: ModalApiImpl;
+  let mockCommit: jest.Mock;
+
+  beforeEach(() => {
+    // 1. Arrange: Create a mock commit function
+    mockCommit = jest.fn() as any;
+
+    // Create a mock store object
+    mockStore = { commit: mockCommit } as any;
+
+    // 2. Arrange: Instantiate the class with the mock store
+    modalApi = new ModalApiImpl(mockStore);
+  });
+
+  it('should open a modal with all default values', () => {
+    // 3. Act: Call the method with only the required component
+    modalApi.open(MockComponent);
+
+    // 4. Assert: Check if the store's commit was called correctly
+    expect(mockCommit).toHaveBeenCalledTimes(1);
+    expect(mockCommit).toHaveBeenCalledWith('modal/openModal', {
+      component:           MockComponent,
+      componentProps:      {},
+      resources:           [],
+      modalWidth:          '600px',
+      closeOnClickOutside: true,
+    });
+  });
+
+  it('should open a modal with custom configuration', () => {
+    const config = {
+      props:               { title: 'Hello' },
+      resources:           [{ id: 1, type: 'node' }],
+      width:               '800px',
+      closeOnClickOutside: false,
+    };
+
+    // 3. Act: Call the method with a config
+    modalApi.open(MockComponent, config);
+
+    // 4. Assert: Check if the config values override the defaults
+    expect(mockCommit).toHaveBeenCalledTimes(1);
+    expect(mockCommit).toHaveBeenCalledWith('modal/openModal', {
+      component:           MockComponent,
+      componentProps:      config.props,
+      resources:           config.resources,
+      modalWidth:          config.width,
+      closeOnClickOutside: config.closeOnClickOutside,
+    });
+  });
+
+  it('should correctly merge a partial config with defaults', () => {
+    const config = { props: { id: '123' } };
+
+    // 3. Act
+    modalApi.open(MockComponent, config);
+
+    // 4. Assert
+    expect(mockCommit).toHaveBeenCalledWith('modal/openModal', {
+      component:           MockComponent,
+      componentProps:      config.props, // Custom
+      resources:           [], // Default
+      modalWidth:          '600px', // Default
+      closeOnClickOutside: true, // Default
+    });
+  });
+});

package/apis/shell/__tests__/notifications.test.ts

@@ -0,0 +1,71 @@
+// notifications.test.ts
+
+import {
+  describe, it, expect, jest, beforeEach
+} from '@jest/globals';
+import { NotificationApiImpl } from '../notifications';
+import { Store } from 'vuex';
+import { NotificationLevel } from '@shell/types/notifications'; // Assuming this path
+
+describe('notificationApiImpl', () => {
+  let mockStore: Store<any>;
+  let notificationApi: NotificationApiImpl;
+  let mockDispatch: jest.Mock;
+
+  beforeEach(() => {
+    // 1. Arrange
+    mockDispatch = jest.fn() as any;
+    mockStore = { dispatch: mockDispatch } as any;
+
+    // 2. Arrange
+    notificationApi = new NotificationApiImpl(mockStore);
+  });
+
+  it('should send a notification and return its ID', async() => {
+    const mockNotificationId = 'notif-12345';
+    const config = { progress: 80 };
+
+    // Arrange: Mock the dispatch to return a promise resolving to the ID
+    mockDispatch.mockResolvedValue(mockNotificationId);
+
+    // 3. Act: Call the async method
+    const result = await notificationApi.send(
+      NotificationLevel.Success,
+      'Test Title',
+      'Test Message',
+      config
+    );
+
+    // 4. Assert
+    expect(mockDispatch).toHaveBeenCalledTimes(1);
+    expect(mockDispatch).toHaveBeenCalledWith(
+      'notifications/add',
+      {
+        level:    NotificationLevel.Success,
+        title:    'Test Title',
+        message:  'Test Message',
+        progress: 80,
+      },
+      { root: true }
+    );
+
+    // Assert the return value
+    expect(result).toBe(mockNotificationId);
+  });
+
+  it('should update notification progress', () => {
+    // 3. Act
+    notificationApi.updateProgress('notif-abc', 75);
+
+    // 4. Assert
+    expect(mockDispatch).toHaveBeenCalledTimes(1);
+    expect(mockDispatch).toHaveBeenCalledWith(
+      'notifications/update',
+      {
+        id:       'notif-abc',
+        progress: 75,
+      },
+      { root: true }
+    );
+  });
+});

package/apis/shell/__tests__/slide-in.test.ts

@@ -0,0 +1,54 @@
+// slide-in.test.ts
+
+import {
+  describe, it, expect, jest, beforeEach
+} from '@jest/globals';
+import { SlideInApiImpl } from '../slide-in'; // Adjust path as needed
+import { Store } from 'vuex';
+
+// A mock component to use in tests
+const MockComponent = { template: '<div>Mock</div>' };
+
+describe('slideInApiImpl', () => {
+  let mockStore: Store<any>;
+  let slideInApi: SlideInApiImpl;
+  let mockCommit: jest.Mock;
+
+  beforeEach(() => {
+    // 1. Arrange
+    mockCommit = jest.fn() as any;
+    mockStore = { commit: mockCommit } as any;
+
+    // 2. Arrange
+    slideInApi = new SlideInApiImpl(mockStore);
+  });
+
+  it('should open a slide-in panel with no config', () => {
+    // 3. Act
+    slideInApi.open(MockComponent);
+
+    // 4. Assert
+    expect(mockCommit).toHaveBeenCalledTimes(1);
+    expect(mockCommit).toHaveBeenCalledWith('slideInPanel/open', {
+      component:      MockComponent,
+      componentProps: {},
+    });
+  });
+
+  it('should open a slide-in panel with a config', () => {
+    const config = {
+      title: 'Test Panel',
+      width: '50%',
+    };
+
+    // 3. Act
+    slideInApi.open(MockComponent, config);
+
+    // 4. Assert
+    expect(mockCommit).toHaveBeenCalledTimes(1);
+    expect(mockCommit).toHaveBeenCalledWith('slideInPanel/open', {
+      component:      MockComponent,
+      componentProps: { ...config }, // The implementation spreads the config
+    });
+  });
+});