@rancher/shell 3.0.11 → 3.0.12-rc.2

package/core/plugin-products-helpers.ts

@@ -0,0 +1,263 @@
+import {
+  RouteRecordRawWithParams, ProductChildGroup, ProductChild,
+  ProductChildCustomPage, ProductChildResourcePage, ProductRegistrationRouteGenerationOptions,
+  OverviewPageRoutingMetadata
+} from '@shell/core/plugin-types';
+import { BLANK_CLUSTER } from '@shell/store/store-types';
+
+function isProductChildGroup(child: ProductChild): child is ProductChildGroup {
+  return 'children' in child && Array.isArray(child.children);
+}
+
+class PluginProductsHelpers {
+  gatherChildrenOrdering(children: ProductChild[]): ProductChild[] {
+    let minWeight = children.reduce((min, item) => {
+      if (typeof item.weight !== 'number') return min;
+
+      return item.weight < min ? item.weight : min;
+    }, Infinity);
+
+    if (minWeight === Infinity) {
+      // 1000 is Root level default weight minus some space
+      minWeight = 999;
+    }
+
+    const processedChildren: ProductChild[] = [];
+
+    children.forEach((child: ProductChild, index) => {
+      const processedChild = { ...child };
+
+      if (processedChild.weight === undefined || processedChild.weight === null) {
+        processedChild.weight = minWeight - (index + 1);
+      }
+
+      if (isProductChildGroup(processedChild)) {
+        processedChild.children = this.gatherChildrenOrdering(processedChild.children);
+      }
+
+      processedChildren.push(processedChild);
+    });
+
+    return processedChildren.sort((a, b) => (b.weight ?? 0) - (a.weight ?? 0));
+  }
+
+  generateTopLevelExtensionSimpleBaseRoute(parentName: string, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
+    const { component, omitPath } = options;
+
+    const route: RouteRecordRawWithParams = {
+      name:   `${ parentName }`,
+      path:   `${ parentName }`,
+      params: { product: parentName },
+      meta:   { product: parentName },
+    };
+
+    if (component) {
+      route.component = component;
+    }
+
+    if (omitPath) {
+      delete route.path;
+    }
+
+    return route;
+  }
+
+  // VIRTUAL TYPE ROUTES
+  generateVirtualTypeRoute(parentName: string, pageChild: ProductChildCustomPage | OverviewPageRoutingMetadata | undefined, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
+    if (options.extendProduct) {
+      return this.generateVirtualTypeRouteForExistingProduct(parentName, pageChild, options);
+    } else {
+      return this.generateVirtualTypeRouteForNewProduct(parentName, pageChild, options);
+    }
+  }
+
+  // VIRTUAL TYPE ROUTES - CLUSTER LEVEL EXTENSION
+  private generateVirtualTypeRouteForExistingProduct(parentName: string, pageChild: ProductChildCustomPage | OverviewPageRoutingMetadata | undefined, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
+    const { component, omitPath } = options;
+    const name = pageChild ? `c-cluster-${ parentName }-${ pageChild.name }` : `c-cluster-${ parentName }`;
+    const path = pageChild ? `c/:cluster/${ parentName }/${ pageChild.name }` : `c/:cluster/${ parentName }`;
+
+    const route: RouteRecordRawWithParams = {
+      name,
+      path,
+      params: { product: parentName },
+      meta:   { product: parentName },
+    };
+
+    if (component) {
+      route.component = component;
+    }
+
+    if (omitPath) {
+      delete route.path;
+    }
+
+    return route;
+  }
+
+  // VIRTUAL TYPE ROUTES - TOP LEVEL EXTENSION
+  private generateVirtualTypeRouteForNewProduct(parentName: string, pageChild: ProductChildCustomPage | OverviewPageRoutingMetadata | undefined, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
+    const { component, omitPath } = options;
+    const name = pageChild ? `${ parentName }-c-cluster-${ pageChild.name }` : `${ parentName }-c-cluster`;
+    const path = pageChild ? `${ parentName }/c/:cluster/${ pageChild.name }` : `${ parentName }/c/:cluster`;
+
+    const route: RouteRecordRawWithParams = {
+      name,
+      path,
+      params: { product: parentName, cluster: BLANK_CLUSTER },
+      meta:   { product: parentName, cluster: BLANK_CLUSTER },
+    };
+
+    if (component) {
+      route.component = component;
+    }
+
+    if (omitPath) {
+      delete route.path;
+    }
+
+    return route;
+  }
+
+  // CONFIGURE TYPE ROUTES
+  generateConfigureTypeRoute(parentName: string, pageChild: ProductChildResourcePage | undefined, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
+    if (options.extendProduct) {
+      return this.generateConfigureTypeRouteForExistingProduct(parentName, pageChild, options);
+    } else {
+      return this.generateConfigureTypeRouteForNewProduct(parentName, pageChild, options);
+    }
+  }
+
+  // CONFIGURE TYPE ROUTES - CLUSTER LEVEL EXTENSION
+  private generateConfigureTypeRouteForExistingProduct(parentName: string, pageChild: ProductChildResourcePage | undefined, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
+    const { component, omitPath } = options;
+
+    const route: RouteRecordRawWithParams = {
+      name:   `c-cluster-${ parentName }-resource`,
+      path:   `c/:cluster/${ parentName }/:resource`,
+      params: { product: parentName, resource: pageChild?.type },
+      meta:   { product: parentName, resource: pageChild?.type },
+    };
+
+    if (component) {
+      route.component = component;
+    }
+
+    if (omitPath) {
+      delete route.path;
+    }
+
+    return route;
+  }
+
+  // CONFIGURE TYPE ROUTES - TOP LEVEL EXTENSION
+  private generateConfigureTypeRouteForNewProduct(parentName: string, pageChild: ProductChildResourcePage | undefined, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
+    const { component, omitPath } = options;
+
+    const route: RouteRecordRawWithParams = {
+      name:   `${ parentName }-c-cluster-resource`,
+      path:   `${ parentName }/c/:cluster/:resource`,
+      params: {
+        product: parentName, cluster: BLANK_CLUSTER, resource: pageChild?.type
+      },
+      meta: {
+        product: parentName, cluster: BLANK_CLUSTER, resource: pageChild?.type
+      },
+    };
+
+    if (component) {
+      route.component = component;
+    }
+
+    if (omitPath) {
+      delete route.path;
+    }
+
+    return route;
+  }
+
+  // RESOURCE ROUTES
+  generateResourceRoutes(parentName: string, pageChild: ProductChildResourcePage, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams[] {
+    if (options.extendProduct) {
+      return this.generateResourceRoutesForExistingProduct(parentName, pageChild);
+    } else {
+      return this.generateResourceRoutesForNewProduct(parentName);
+    }
+  }
+
+  // RESOURCE ROUTES - CLUSTER LEVEL EXTENSION
+  private generateResourceRoutesForExistingProduct(parentName: string, pageChild: ProductChildResourcePage): RouteRecordRawWithParams[] {
+    const interopDefault = (promise: Promise<any>) => promise.then((page) => page.default || page);
+
+    return [
+      {
+        name:      `c-cluster-${ parentName }-resource`,
+        path:      `c/:cluster/${ parentName }/:resource`,
+        component: () => interopDefault(import('@shell/pages/c/_cluster/_product/_resource/index.vue')),
+        meta:      { product: parentName, resource: pageChild.type }
+      },
+      {
+        name:      `c-cluster-${ parentName }-resource-create`,
+        path:      `c/:cluster/${ parentName }/:resource/create`,
+        component: () => interopDefault(import('@shell/pages/c/_cluster/_product/_resource/create.vue')),
+        meta:      { product: parentName, resource: pageChild.type }
+      },
+      {
+        name:      `c-cluster-${ parentName }-resource-id`,
+        path:      `c/:cluster/${ parentName }/:resource/:id`,
+        component: () => interopDefault(import('@shell/pages/c/_cluster/_product/_resource/_id.vue')),
+        meta:      {
+          product: parentName, resource: pageChild.type, asyncSetup: true
+        }
+      },
+      {
+        name:      `c-cluster-${ parentName }-resource-namespace-id`,
+        path:      `c/:cluster/${ parentName }/:resource/:namespace/:id`,
+        component: () => interopDefault(import('@shell/pages/c/_cluster/_product/_resource/_namespace/_id.vue')),
+        meta:      {
+          product: parentName, resource: pageChild.type, asyncSetup: true
+        }
+      }
+    ];
+  }
+
+  // RESOURCE ROUTES - TOP LEVEL EXTENSION
+  private generateResourceRoutesForNewProduct(parentName: string) {
+    const interopDefault = (promise: Promise<any>) => promise.then((page) => page.default || page);
+
+    return [
+      {
+        name:      `${ parentName }-c-cluster-resource`,
+        path:      `${ parentName }/c/:cluster/:resource`,
+        component: () => interopDefault(import('@shell/pages/c/_cluster/_product/_resource/index.vue')),
+        meta:      { product: parentName, cluster: BLANK_CLUSTER }
+      },
+      {
+        name:      `${ parentName }-c-cluster-resource-create`,
+        path:      `${ parentName }/c/:cluster/:resource/create`,
+        component: () => interopDefault(import('@shell/pages/c/_cluster/_product/_resource/create.vue')),
+        meta:      { product: parentName, cluster: BLANK_CLUSTER }
+      },
+      {
+        name:      `${ parentName }-c-cluster-resource-id`,
+        path:      `${ parentName }/c/:cluster/:resource/:id`,
+        component: () => interopDefault(import('@shell/pages/c/_cluster/_product/_resource/_id.vue')),
+        meta:      {
+          product: parentName, cluster: BLANK_CLUSTER, asyncSetup: true
+        }
+      },
+      {
+        name:      `${ parentName }-c-cluster-resource-namespace-id`,
+        path:      `${ parentName }/c/:cluster/:resource/:namespace/:id`,
+        component: () => interopDefault(import('@shell/pages/c/_cluster/_product/_resource/_namespace/_id.vue')),
+        meta:      {
+          product: parentName, cluster: BLANK_CLUSTER, asyncSetup: true
+        }
+      }
+    ];
+  }
+}
+
+const pluginProductsHelpers = new PluginProductsHelpers();
+
+export default pluginProductsHelpers;

package/core/plugin-products-top-level.ts

@@ -0,0 +1,66 @@
+import { IExtension } from '@shell/core/types';
+import { ProductChild, ProductMetadata, ProductSinglePage } from '@shell/core/plugin-types';
+import EmptyProductPage from '@shell/components/EmptyProductPage.vue';
+import pluginProductsHelpers from '@shell/core/plugin-products-helpers';
+import { BasePluginProduct } from '@shell/core/plugin-products-base';
+import { isProductSinglePage } from '@shell/core/plugin-products-type-guards';
+
+/**
+ * Represents a new top-level product being added by an extension
+ * @internal
+ */
+export class TopLevelPluginProduct extends BasePluginProduct {
+  get isNewProduct(): boolean {
+    return true;
+  }
+
+  constructor(plugin: IExtension, product: ProductMetadata | ProductSinglePage | string, config: ProductChild[]) {
+    super(config);
+
+    // Convenience/bridge method: create a basic product from just a name string
+    if (typeof product === 'string') {
+      product = {
+        name:  product,
+        label: product,
+      };
+    }
+
+    let prodName = product.name;
+
+    // the goal here is not to interfere with vue-router route names, which use dashes
+    if (prodName.includes('-')) {
+      prodName = prodName.replaceAll('-', '');
+    }
+
+    // convert this to "string" to match all types moving forward
+    // doesn't impact anything, fixes build problems of extensions
+    // and allows extensions to use either string literal or enum value for product name
+    this.name = prodName;
+    this.product = product;
+
+    // register the product as a top-level product in the plugin object (will be needed for routes correction when on list views for top-level products)
+    plugin._registerTopLevelProduct();
+
+    this.processConfigChildren();
+
+    // If the product has a `component` field, then this is a single page product
+    if (isProductSinglePage(product)) {
+      // Add the route to vue-router (here we go with the 'plain' layout for simple single page products)
+      const route = pluginProductsHelpers.generateTopLevelExtensionSimpleBaseRoute(this.name, { component: product.component });
+
+      plugin.addRoute('plain', route);
+    } else if (this.config.length === 0) {
+      // If no config is provided, add a default empty page
+      this.config = [{
+        name:      'main',
+        label:     'Main',
+        component: EmptyProductPage,
+      }];
+
+      this.addRoutes(plugin, this.name, this.config);
+    } else {
+      // This is the general case - product with config items and no single page component
+      this.addRoutes(plugin, this.name, this.config);
+    }
+  }
+}

package/core/plugin-products-type-guards.ts

@@ -0,0 +1,33 @@
+import {
+  ProductChild, ProductChildGroup, ProductMetadata,
+  ProductSinglePage, ProductChildCustomPage, ProductChildResourcePage
+} from '@shell/core/plugin-types';
+
+/**
+ * Type guard functions for discriminating union types
+ * @internal
+ */
+
+export function isProductSinglePage(product: ProductMetadata | ProductSinglePage): product is ProductSinglePage {
+  return 'component' in product && product.component !== undefined;
+}
+
+export function isProductChildGroup(child: ProductChild): child is ProductChildGroup {
+  return 'children' in child;
+}
+
+export function isProductChildWithComponent(child: ProductChild): child is ProductChildCustomPage {
+  return 'component' in child && child.component !== undefined && !isProductChildGroup(child);
+}
+
+export function isProductChildWithType(child: ProductChild): child is ProductChildResourcePage {
+  return 'type' in child && typeof child.type === 'string' && !isProductChildGroup(child);
+}
+
+export function hasNameProperty(child: ProductChild): child is ProductChild & { name: string } {
+  return 'name' in child && typeof child.name === 'string';
+}
+
+export function hasTypeProperty(child: ProductChild): child is ProductChild & { type: string } {
+  return 'type' in child && typeof child.type === 'string';
+}

package/core/plugin-products.ts

@@ -0,0 +1,50 @@
+import { IExtension } from '@shell/core/types';
+import {
+  StandardProductName, ProductChild,
+  ProductMetadata, ProductSinglePage,
+} from '@shell/core/plugin-types';
+import { BasePluginProduct } from '@shell/core/plugin-products-base';
+import { TopLevelPluginProduct } from '@shell/core/plugin-products-top-level';
+import { ExtendingPluginProduct } from '@shell/core/plugin-products-extending';
+
+/**
+ * Factory class for creating plugin products
+ * Maintains backward compatibility with the original PluginProduct class
+ * @internal
+ */
+export class PluginProduct {
+  private instance: BasePluginProduct;
+
+  constructor(plugin: IExtension, product: StandardProductName | string | ProductMetadata | ProductSinglePage, config: ProductChild[]) {
+    if (typeof product === 'object' && product.name) {
+      // This is a new product being added
+      this.instance = new TopLevelPluginProduct(plugin, product, config);
+    } else if (typeof product === 'string') {
+      // This is extending an existing standard product
+      this.instance = new ExtendingPluginProduct(plugin, product, config);
+    } else {
+      // at this point we may not know the product name
+      throw new Error('Extensions product registration error ::: Invalid product');
+    }
+  }
+
+  /**
+   * Convenience/bridge method: create a new top-level product from just a name string.
+   * The product will use EmptyProductPage as its default page.
+   */
+  static fromName(plugin: IExtension, productName: string): PluginProduct {
+    const instance = Object.create(PluginProduct.prototype);
+
+    instance.instance = new TopLevelPluginProduct(plugin, productName, []);
+
+    return instance;
+  }
+
+  apply(plugin: IExtension, store: any): void {
+    this.instance.apply(plugin, store);
+  }
+
+  get newProduct(): boolean {
+    return this.instance.isNewProduct;
+  }
+}

package/core/plugin-types.ts

@@ -0,0 +1,237 @@
+import type { RouteComponent, RouteRecordRaw } from 'vue-router';
+import type { PluginRouteRecordRaw } from './types';
+import { NAME as EXPLORER_PROD_NAME } from '@shell/config/product/explorer.js';
+import { NAME as CLUSTER_MAN_PROD_NAME } from '@shell/config/product/manager.js';
+import { NAME as SETTINGS_PROD_NAME } from '@shell/config/product/settings.js';
+import { NAME as AUTH_PROD_NAME } from '@shell/config/product/auth.js';
+import { ProductOptions } from '@shell/core/types';
+
+type Async<T> = () => Promise<T>;
+
+export type RouteRecordRawWithParams = Omit<RouteRecordRaw, 'redirect' | 'children' | 'path'> & {
+  /** Path for route - can include dynamic segments like ':id'. Based on vue-router routes */
+  path?: string;
+  /** Params for route - key-value pairs representing route parameters */
+  params?: Record<string, any>;
+  /** Child routes */
+  children?: RouteRecordRawWithParams[];
+  /** Optional redirect */
+  redirect?: RouteRecordRaw['redirect'];
+};
+
+/**
+ * Product registration route generation options
+ */
+export type ProductRegistrationRouteGenerationOptions = {
+  /**
+   * Whether to generate the route for an existing product - extending a product - or a new top level product
+   */
+  extendProduct? : boolean;
+  /**
+   * Component to be used for the route (used in virtualType and configureType routes)
+   */
+  component?: any;
+  /**
+   * Generated route should omit the path property
+   */
+  omitPath?: boolean;
+}
+
+/**
+ * Represents the allowed extensible products in Rancher Dashboard
+ */
+export const StandardProductNames = {
+  EXPLORER: EXPLORER_PROD_NAME,
+  MANAGER:  CLUSTER_MAN_PROD_NAME,
+  SETTINGS: SETTINGS_PROD_NAME,
+  AUTH:     AUTH_PROD_NAME,
+} as const;
+
+/**
+ * Type representing a standard product name value
+ */
+export type StandardProductName = (typeof StandardProductNames)[keyof typeof StandardProductNames];
+
+/**
+ * Represents allowed configuration for a child page
+ */
+export type ProductChildMetadata = {
+  /** Product name/unique identifier for the product */
+  name: string;
+  /** Ordering weight for the among its siblings, if applicable */
+  weight?: number;
+} & (
+  /** Human-readable label for the child page
+   * Either label or labelKey are required */
+  { label: string; labelKey?: string }
+  /** Translation key for the label of the child page
+   * Either label or labelKey are required */
+  | { labelKey: string; label?: string }
+);
+
+/**
+ * Represents the allowed configuration for a custom page (virtualType)
+ */
+export type VirtualTypeConfiguration = {
+  /** Display only if condition is met (relates to IF_HAVE in shell/store/type-map) */
+  ifHave?: boolean;
+  /** Display only if feature is present (relates to shell/store/features) */
+  ifFeature?: string;
+  /** Display only if resource type exists */
+  ifHaveType?: string;
+  /** Used in conjunction with "ifHaveType", display only if resource type allows this verb (GET, POST, PUT, DELETE) */
+  ifHaveVerb?: string;
+  /** Display label for the custom page */
+  label?: string;
+  /** Translation key for the label */
+  labelKey?: string;
+  /** Name of the page (unique identifier) */
+  name?: string;
+  /** Entry route definition for this custom page */
+  route?: RouteRecordRawWithParams | PluginRouteRecordRaw | Object;
+  /** Icon for the custom page (relates to icons in https://github.com/rancher/icons) */
+  icon?: 'compass';
+  /** Whether this custom page is namespaced or not */
+  namespaced?: boolean;
+  /** Ordering weight for the custom page */
+  weight?: number;
+  /** Whether this custom page is exact match */
+  exact?: boolean;
+  /** Whether this custom page will act as an overview page */
+  overview?: boolean;
+  /** Whether this custom page has an exact path match */
+  'exact-path'?: boolean;
+}
+
+/**
+ * Represents the allowed configuration for a resource page (configureType)
+ */
+export type ConfigureTypeConfiguration = {
+  /** Override for the name displayed */
+  displayName?: string;
+  /** Override for the create button string on a list view */
+  listCreateButtonLabelKey?: string;
+  /** If false, disable create even if schema says it's allowed */
+  isCreatable?: boolean;
+  /** If false, disable for edit */
+  isEditable?: boolean;
+  /** If false, disable for remove/delete */
+  isRemovable?: boolean;
+  /** If false, hide state in columns and masthead */
+  showState?: boolean;
+  /** If false, hide age in columns and masthead */
+  showAge?: boolean;
+  /** If false, hide masthead config button in view mode */
+  showConfigView?: boolean;
+  /** If false, hide masthead in list view */
+  showListMasthead?: boolean;
+  /** If false, cannot edit or show yaml */
+  canYaml?: boolean;
+  /** Show the Masthead in the edit resource component */
+  resourceEditMasthead?: boolean;
+  /** Entry route definition for this resource page */
+  customRoute?: RouteRecordRawWithParams;
+  /** Hide this type from the nav/search bar on downstream clusters (will only show in "local" cluster) */
+  localOnly?: boolean;
+  // resource: undefined; // Use this resource in ResourceDetails instead
+  // resourceDetail: undefined; // Use this resource specifically for ResourceDetail's detail component
+  // resourceEdit: undefined; // Use this resource specifically for ResourceDetail's edit component
+  // depaginate: undefined; // Use this to depaginate requests for this type
+  // notFilterNamespace: undefined; // Define namespaces that do not need to be filtered
+  // used in configureType options, to be typed later if needed
+  // listGroups: [
+  //       {
+  //         icon:       'icon-role-binding',
+  //         value:      'node',
+  //         field:      'roleDisplay',
+  //         hideColumn: ROLE.name,
+  //         tooltipKey: 'resourceTable.groupBy.role'
+  //       }
+  //     ]
+}
+
+/**
+ * Represents a Vue component or an async function that resolves to a Vue component, used for route components in product configuration
+ */
+export type VueRouteComponent = RouteComponent | Async<RouteComponent>;
+
+/**
+ * Metadata for route generation to a product overview page
+ */
+export type OverviewPageRoutingMetadata = {
+  /** Name of the overview page */
+  name: string;
+  /** Component to render for the overview page */
+  component: VueRouteComponent;
+}
+
+/**
+ * Represents a custom page with a component
+ */
+export type ProductChildCustomPage = ProductChildMetadata & {
+  /** Component to render for this custom page */
+  component: VueRouteComponent;
+  /** Optional configuration for the page */
+  config?: VirtualTypeConfiguration;
+};
+
+/**
+ * Represents a resource page with a type (K8s resource)
+ */
+export type ProductChildResourcePage = {
+  /** K8s resource type name for a resource page */
+  type: string;
+  /** Optional configuration for the resource page */
+  config?: ConfigureTypeConfiguration;
+  /** Ordering weight for this page among its siblings */
+  weight?: number;
+};
+
+/**
+ * Represents a page item (custom page or resource page) in a product's config
+ * - For custom pages: use `component` with `name` and `label`/`labelKey`
+ * - For resource pages: use `type` with optional `config` and `headers`
+ */
+export type ProductChildPage = ProductChildCustomPage | ProductChildResourcePage;
+
+/**
+ * Represents a product child in the navigation
+ * This can be a type, a group, or a route.
+ */
+export type ProductChild = ProductChildGroup | ProductChildPage; // eslint-disable-line no-use-before-define
+
+/**
+ * Represents a group of child pages in a product configuration
+ */
+export type ProductChildGroup = ProductChildMetadata & {
+  component?: VueRouteComponent;
+  children: ProductChild[];
+  /** Default child to navigate to */
+  default?: string;
+};
+
+/**
+ * Represents the allowed configuration for a product
+ */
+export type ProductMetadata = Omit<ProductOptions, 'name' | 'label' | 'labelKey' | 'category' | 'to' | 'version' | 'inStore'> & {
+  /**
+   * Product name (unique identifier)
+   */
+  name: string;
+} & (
+  /** Human-readable label for the product
+   * Either label or labelKey are required */
+  | { label: string; labelKey?: string }
+  /** Translation key for the label of the product
+   * Either label or labelKey are required */
+  | { labelKey: string; label?: string }
+);
+
+/**
+ * Represents a single page product, which is a product that only has one page and
+ * therefore does not need to be represented in the navigation as a group with children.
+ */
+export type ProductSinglePage = ProductMetadata & {
+  /** Component to render for this product (single page product) */
+  component: VueRouteComponent;
+};