@rancher/shell 3.0.12-rc.5 → 3.0.12-rc.6

package/core/plugin-products-external.ts

@@ -0,0 +1,380 @@
+import { ProductFunction } from '@shell/core/plugin';
+import { HeaderOptions } from '@shell/core/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 { RouteComponent } from 'vue-router';
+
+type Async<T> = () => Promise<T>;
+
+/**
+ * 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 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>;
+
+// --------------  Page Related Resource --------------
+// When updating external page types also update where they're converted to the internal page type
+// i.e. `TypeMapVirtualType` or `TypeMapConfigureType` usage in shell/core/plugin-products-base.ts
+
+/**
+ * Type that enforces either a `label` or `labelKey`
+ */
+type LabelOrLabelKey = (
+  /** 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 custom page with a component
+ */
+export type ProductChildCustomPage = LabelOrLabelKey & {
+  /** Product name/unique identifier for the product */
+  name: string;
+
+  /** Component to render for this custom page */
+  component: VueRouteComponent;
+
+  /** Determine when this product is enabled and shown */
+  enable?: {
+    /** 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;
+  };
+
+  /** Control how the child displays in the side menu  */
+  sideMenu?: {
+    /** Ordering weight for this page among its siblings */
+    weight?: number;
+  }
+
+  /** Control how resources are handled in this product */
+  resource?: {
+    /** Whether resources this page represents is namespaced */
+    namespaced?: boolean;
+  }
+};
+
+/**
+ * Represents a resource page with a type (K8s resource)
+ */
+export type ProductChildResourcePage = {
+  /** K8s resource type name for a resource page */
+  type: string;
+
+  /**
+   * Optional. Override the label for this page
+   */
+  label?: string
+
+  /** Control how the child displays in the side menu  */
+  sideMenu?: {
+    /** Ordering weight for this page among its siblings */
+    weight?: number;
+    /** Hide this type from the nav/search bar on downstream clusters (will only show in "local" cluster) */
+    localOnly?: boolean;
+  }
+
+  /** Control how the product displays some information  */
+  display?: {
+    /** If false, hide state in columns and masthead */
+    showState?: boolean;
+    /** If false, hide age in columns and masthead */
+    showAge?: boolean;
+  }
+
+  /** Control what actions and features can be carried out for this resource type */
+  can?: {
+    /** If false, disable create even if schema says it's allowed */
+    create?: boolean;
+    /** If false, disable for edit */
+    edit?: boolean;
+    /** If false, disable for remove/delete */
+    remove?: boolean;
+    /** If false, cannot edit or show yaml */
+    yaml?: boolean;
+  }
+
+  /** Control how this resource behaves in resource list, detail and create/edit pages */
+  views?: {
+
+    /** Control how this resource behaves in a resource list page */
+    list?: {
+      /** Override for the create button string on a list view */
+      createLabelKey?: string;
+
+      /** If false, hide masthead in list view. Defaults to true */
+      showListMasthead?: boolean;
+    }
+
+    /** Control how this resource behaves in a resource detail page */
+    detail?: {
+      /** If false, hide masthead config button in view mode. Defaults to true */
+      showConfigView?: boolean;
+    }
+
+    /** Control how this resource behaves in a resource create/edit page */
+    createEdit?: {
+      /** Show the Masthead in the edit resource component. Defaults to true */
+      showMasthead?: boolean;
+    }
+  }
+
+  /** Control how all lists that show this resource behave  */
+  listConfig?: {
+    /** Table headers for this resource type (server-side pagination) */
+    headers?: HeaderOptions[];
+    /** Whether to hide bulk actions for this resource */
+    hideBulkActions?: boolean;
+  }
+};
+
+/**
+ * Represents a page item (custom page or resource page) in a product's config
+ */
+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 = LabelOrLabelKey & {
+  /** Product name/unique identifier for the product */
+  name: string;
+
+  /** Component to render for this group */
+  component?: VueRouteComponent;
+
+  /** Control how the child displays menu items in the side menu  */
+  sideMenu: {
+    /**
+    * Add entries to the side menu
+    */
+    children: ProductChild[];
+    /** Ordering weight for this group among its siblings */
+    weight?: number;
+    /** Default child to navigate to */
+    default?: string;
+  }
+};
+
+// --------------  Product Related Resource --------------
+
+// When updating external product types also update where they're converted to the internal product type
+// i.e. `TypeMapProduct` usage in shell/core/plugin-products-base.ts
+
+/**
+ * Represents the allowed configuration for a product
+ */
+type _ProductMetadata = LabelOrLabelKey & {
+  /**
+   * Product name (unique identifier)
+   */
+  name: string;
+
+  /**
+   * Control conditions on when to show the product
+   */
+  enable?: {
+    /**
+     * Only load the product if the feature is present
+     */
+    ifFeature?: string | RegExp;
+
+    /**
+     * Only load the product if the type is present
+     */
+    ifHave?: string;
+
+    /**
+     * Only load the product if the group is present
+     */
+    ifHaveGroup?: string | RegExp;
+
+    /**
+     * Only load the product if the type is present
+     */
+    ifHaveType?: string | RegExp;
+
+    /**
+     * Hide the product if the type is present (opposite of ifHaveType)
+     */
+    ifNotHaveType?: string | RegExp;
+  }
+
+  /** Control what appears in the UI's main application header */
+  appHeader?: {
+    /**
+     * Hide the Copy KubeConfig button in the header
+     */
+    hideCopyConfig?: boolean;
+
+    /**
+     * Hide the Download KubeConfig button in the header
+     */
+    hideKubeConfig?: boolean;
+
+    /**
+     * Hide the Kubectl Shell button in the header
+     */
+    hideKubeShell?: boolean;
+
+    /**
+    * Show the cluster info
+    */
+    showClusterInfo?: boolean;
+
+    /**
+     * Show the namespace filter in the header
+     */
+    showNamespaceFilter?: boolean;
+
+    /**
+     * Show a product icon in the header
+     */
+    icon?: string;
+  },
+
+  /**
+   * Control what appears in the vertical side bar on the left of the UI
+   */
+  sideBar?: {
+    /**
+     * A number used to determine where in navigation this item will be placed. The highest number will be at the top of the list.
+     */
+    weight?: number;
+
+    /**
+     * The icon to display in the side bar for this product
+     */
+    icon: {
+      /**
+      * Icon pack name
+      */
+      name?: string;
+
+      /**
+       * Alternative to the icon property. Uses require
+       */
+      svg?: Function;
+    },
+
+  }
+
+  /**
+   * Control how resources are fetched, filtered and stored
+   */
+  resources?: {
+    /**
+     * Hide the system resources in lists
+     */
+    hideSystemResources?: boolean;
+
+    /**
+    * The vuex store that this product should use by default i.e. 'management'
+    */
+    store?: string;
+  }
+
+  /**
+   * Indicates whether UI Extensions can add pages to this product
+   */
+  extendable?: boolean;
+}
+
+export type ProductMetadata = _ProductMetadata
+
+/**
+ * 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 ProductMetadataSinglePage = ProductMetadata & {
+  /** Component to render for this product (single page product) */
+  component: VueRouteComponent;
+};
+
+// --------------  Extension methods --------------
+
+export interface IExtensionProducts {
+  /**
+   * Register a top-level product as a flag on the plugin
+   * @internal - DO NOT USE - Internal API only
+   */
+  _registerTopLevelProduct(): void;
+
+  /**
+   *
+   * @internal - DO NOT USE - Internal API only
+   */
+  _setStartRouteWithProduct(value: boolean): void;
+
+  /**
+   * Add a product to the sidebar, with children and a side menu for navigation for internal pages
+   * @param product
+   * @param sideMenu Pages associated with the product. These will appear in the side menu
+   */
+  addProduct(product: ProductMetadata, sideMenu: ProductChildPage[]): void;
+  addProduct(product: ProductMetadata, sideMenu: ProductChildGroup[]): void;
+  addProduct(product: ProductMetadata, sideMenu: ProductChild[]): void;
+
+  /**
+   * Add a product to the sidebar, without children (no side menu, single page only)
+   * @param product
+   */
+  addProduct(product: ProductMetadataSinglePage): void;
+
+  /**
+   * Add a product with just a name (convenience/bridge method for quick setup).
+   * Creates a basic product with an empty page component automatically.
+   * This is useful for getting started quickly - expand to the full API once you're ready to add custom pages.
+   * @param productName Simple product name - will be used as both the name and label
+   */
+  addProduct(productName: string): void;
+
+  /**
+   * Add a product to the sidebar (deprecated, use other signatures of addProduct instead)
+   *
+   * Once other `addProduct` signatures reach maturity this will be deprecated
+   * @param importFn Function that will import the module containing a product definition
+   */
+  addProduct(importFn: ProductFunction): void;
+
+  /**
+   * Extend an existing product in Rancher, with children and a side menu for navigation for internal pages
+   *
+   * @param productName Name of the product to be extended
+   * @param sideMenu Pages that will be added to the product. These will appear in the side menu
+   */
+  extendProduct(productName: StandardProductName | string, sideMenu: ProductChildPage[]): void;
+  extendProduct(productName: StandardProductName | string, sideMenu: ProductChildGroup[]): void;
+  extendProduct(productName: StandardProductName | string, sideMenu: ProductChild[]): void;
+}

package/core/plugin-products-helpers.ts

@@ -1,20 +1,21 @@
-import {
-  RouteRecordRawWithParams, ProductChildGroup, ProductChild,
-  ProductChildCustomPage, ProductChildResourcePage, ProductRegistrationRouteGenerationOptions,
-  OverviewPageRoutingMetadata
-} from '@shell/core/plugin-types';
+import { ProductChild, ProductChildCustomPage, ProductChildResourcePage } from '@shell/core/plugin-products-external';
+import { ProductRegistrationRouteGenerationOptions } from '@shell/core/plugin-products-internal';
+import { isProductChildGroup } from '@shell/core/plugin-products-type-guards';
+import { RouteRecordRawWithParams } 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 {
+  private weightFromProductChild(item: ProductChild): number | undefined {
+    return (item as ProductChildCustomPage).sideMenu?.weight || (item as ProductChildResourcePage).sideMenu?.weight;
+  }
+
   gatherChildrenOrdering(children: ProductChild[]): ProductChild[] {
     let minWeight = children.reduce((min, item) => {
-      if (typeof item.weight !== 'number') return min;
+      const weight = this.weightFromProductChild(item);
+
+      if (typeof weight !== 'number') return min;
 
-      return item.weight < min ? item.weight : min;
+      return weight < min ? weight : min;
     }, Infinity);
 
     if (minWeight === Infinity) {
@@ -27,18 +28,21 @@ class PluginProductsHelpers {
     children.forEach((child: ProductChild, index) => {
       const processedChild = { ...child };
 
-      if (processedChild.weight === undefined || processedChild.weight === null) {
-        processedChild.weight = minWeight - (index + 1);
+      if (processedChild.sideMenu?.weight === undefined || processedChild.sideMenu?.weight === null) {
+        if (!processedChild.sideMenu) {
+          processedChild.sideMenu = {};
+        }
+        processedChild.sideMenu.weight = minWeight - (index + 1);
       }
 
       if (isProductChildGroup(processedChild)) {
-        processedChild.children = this.gatherChildrenOrdering(processedChild.children);
+        processedChild.sideMenu.children = this.gatherChildrenOrdering(processedChild.sideMenu.children);
       }
 
       processedChildren.push(processedChild);
     });
 
-    return processedChildren.sort((a, b) => (b.weight ?? 0) - (a.weight ?? 0));
+    return processedChildren.sort((a, b) => (b.sideMenu?.weight ?? 0) - (a.sideMenu?.weight ?? 0));
   }
 
   generateTopLevelExtensionSimpleBaseRoute(parentName: string, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
@@ -63,19 +67,19 @@ class PluginProductsHelpers {
   }
 
   // VIRTUAL TYPE ROUTES
-  generateVirtualTypeRoute(parentName: string, pageChild: ProductChildCustomPage | OverviewPageRoutingMetadata | undefined, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
+  generateVirtualTypeRoute(parentName: string, childName: string | undefined, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
     if (options.extendProduct) {
-      return this.generateVirtualTypeRouteForExistingProduct(parentName, pageChild, options);
+      return this.generateVirtualTypeRouteForExistingProduct(parentName, childName, options);
     } else {
-      return this.generateVirtualTypeRouteForNewProduct(parentName, pageChild, options);
+      return this.generateVirtualTypeRouteForNewProduct(parentName, childName, options);
     }
   }
 
   // VIRTUAL TYPE ROUTES - CLUSTER LEVEL EXTENSION
-  private generateVirtualTypeRouteForExistingProduct(parentName: string, pageChild: ProductChildCustomPage | OverviewPageRoutingMetadata | undefined, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
+  private generateVirtualTypeRouteForExistingProduct(parentName: string, childName: string | 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 name = childName ? `c-cluster-${ parentName }-${ childName }` : `c-cluster-${ parentName }`;
+    const path = childName ? `c/:cluster/${ parentName }/${ childName }` : `c/:cluster/${ parentName }`;
 
     const route: RouteRecordRawWithParams = {
       name,
@@ -96,10 +100,10 @@ class PluginProductsHelpers {
   }
 
   // VIRTUAL TYPE ROUTES - TOP LEVEL EXTENSION
-  private generateVirtualTypeRouteForNewProduct(parentName: string, pageChild: ProductChildCustomPage | OverviewPageRoutingMetadata | undefined, options: ProductRegistrationRouteGenerationOptions = {}): RouteRecordRawWithParams {
+  private generateVirtualTypeRouteForNewProduct(parentName: string, childName: string | 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 name = childName ? `${ parentName }-c-cluster-${ childName }` : `${ parentName }-c-cluster`;
+    const path = childName ? `${ parentName }/c/:cluster/${ childName }` : `${ parentName }/c/:cluster`;
 
     const route: RouteRecordRawWithParams = {
       name,

package/core/plugin-products-internal.ts

@@ -0,0 +1,207 @@
+import {
+  ProductMetadata,
+  ProductChildResourcePage,
+  ProductChildCustomPage,
+} from '@shell/core/plugin-products-external';
+import { PaginationHeaderOptions, PluginRouteRecordRaw } from '@shell/core/types';
+
+/**
+ * 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;
+  /**
+   * @internal
+   * Whether the route should start with the product name or not (e.g. "my-product/c/:cluster/:resource" vs "c/:cluster/my-product/:resource")
+   * only to be used in very special usecases (internal use only - check FLEET product config for an example)
+   * */
+  startRouteWithProduct?: boolean;
+}
+
+// --------------  Page Related Resource --------------
+// When updating external page types also update where they're converted to the internal page type
+// i.e. `TypeMapVirtualType` or `TypeMapConfigureType` usage in shell/core/plugin-products-base.ts
+
+/**
+ * Conceptually a `TypeMapVirtualType`
+ */
+export type ProductChildCustomPageInternal = ProductChildCustomPage & {
+  navigation?: {
+    /** Whether this custom page is exact match */
+    exact?: boolean;
+    /** Whether this custom page has an exact path match */
+    'exact-path'?: boolean;
+  }
+}
+
+/**
+ * Conceptually a `TypeMapConfigureType`
+ */
+export type ProductChildResourcePageInternal = ProductChildResourcePage & {
+  /** Control how all lists that show this resource behave  */
+  listConfig?: {
+    /** Table headers for this resource type (client-side pagination) */
+    localHeaders?: PaginationHeaderOptions[];
+
+    /**
+     * Whether this custom page has list groups (definition for grouping items in the list view)
+     */
+    listGroups?: {
+      /** Icon for the group (relates to icons in rancher-icons */
+      icon?: string;
+      /** Value for the group (used for grouping items in the list view) */
+      value?: string;
+      /** Field for the group (used for grouping items in the list view) */
+      field?: string;
+      /** Column to hide when this group is active */
+      hideColumn?: string;
+      /** Tooltip key for the group */
+      tooltipKey?: string;
+    }[];
+
+    /**
+     * Whether the provided list groups will override the default grouping options (e.g. group by namespace, group by cluster, etc.) or be added to them
+     */
+    listGroupsWillOverride?: boolean;
+
+    /**
+    * Use this to configure subtypes that should be shown in the list view for this type (e.g. show "pods" and "deployments" in the list view for "workloads")
+    */
+    subTypes?: string[];
+  }
+
+  /** Control how the child displays in the side menu  */
+  sideMenu?: {
+    /** Whether to hide this resource from the side-menu entirely */
+    hideFromNav?: boolean;
+  }
+
+  /** Control how resources are handled in this product */
+  resource?: {
+   /**
+   * When requests are made to fetch this resource, outside of paginated requests, and they are paged.. iteratively fetch all pages
+   *
+   * We want to move away from this and use one of the new paginated requests to only fetch the data we need
+   */
+    depaginate?: boolean;
+  }
+}
+
+// --------------  Product Related Resource --------------
+
+// When updating external product types also update where they're converted to the internal product type
+// i.e. `TypeMapProduct` usage in shell/core/plugin-products-base.ts
+
+// -----
+export type ProductMetadataInternal = ProductMetadata & {
+  /**
+   * The category this product belongs under. i.e. 'config'
+   */
+  category?: string;
+
+  /** Do not use - internal use only */
+  version?: number;
+
+  /** Control what appears in the UI's main application header */
+  appHeader?: {
+    /**
+    * Hide the Namespace location
+    */
+    hideNamespaceLocation?: boolean;
+    /**
+    *  controls whether a workspace switcher dropdown appears in the header (instead of the namespace filter) if set to true
+    */
+    showWorkspaceSwitcher?: boolean;
+  },
+
+  /**
+  * Control what appears in the vertical side bar on the left of the UI
+  */
+  sideBar? :{
+    /**
+    * Control page links
+    */
+    navigation?: {
+      /**
+       * The route that the product will lead to if click on in navigation.
+       */
+      to?: PluginRouteRecordRaw;
+    }
+  }
+
+  /** Control how the child displays in the side menu  */
+  sideMenu?: {
+    /**
+     * @internal
+     * Use `renameGroups` on the product metadata to remap group display names in the side-menu. Each entry matches a group's internal ID (via string or regex) and replaces its display label with a new name. This only changes how the group is labelled in the UI — it does not move resources between groups.
+     *
+     * The `groupSelector` is evaluated against group internal IDs. It can be an exact string or a `RegExp` pattern. The `newName` value is the new display name.
+     *
+     */
+    renameGroups?: {
+      /** String or regex to match against group internal IDs */
+      groupSelector: RegExp | string;
+      /** Display name to use for matching groups */
+      newName: string;
+    }[];
+
+    /**
+     * @internal
+     *
+     * Use `moveToGroup` on the product metadata to move pages (resource types or custom pages) into specific side-menu groups. This is useful when a page should appear inside a group but isn't defined as a child of that group in the config.
+     * Each entry identifies a page by its `entryId` — the resource `type` string or the custom page `name` — and moves it into the specified group. Use the group's `name` as you defined it in your config.
+     *
+     * Note: The `entryId` must match a page declared in the same product config — either a resource page's `type` or a custom page's `name`. The target `groupName` must be a `ProductChildGroup` defined in the same config. If either is not found, an error is thrown at registration time listing the available options. Only exact string identifiers are supported (no regex).
+     *
+     * The optional `weight` parameter controls precedence when multiple `moveToGroup` rules target the same page (default: `5`). Higher weight takes precedence.
+    */
+    moveToGroup?: {
+      /** Page identifier — the resource `type` string or the custom page `name` */
+      entryId: string;
+      /** Target group name as defined in your group config (`name` property) */
+      groupName: string;
+      /** Ordering weight for the mapping (default: 5). Higher weight takes precedence when multiple rules match */
+      weight?: number;
+    }[];
+
+    /**
+     * @internal
+     *
+     * maps to DSL ignoreGroup
+     *
+     * Use `ignoreGroups` on the product metadata to hide specific side-menu groups. Each entry specifies a `groupSelector` to match group names — either an exact string or a regex pattern.
+     *
+     * The `condition` callback is optional. When provided, it receives the store getters and returns `true` to hide the group (conditional hide). When omitted, the group is always hidden (unconditional hide).
+     *
+     */
+    ignoreGroups?: {
+      /** String or regex to match against group names */
+      groupSelector: string | RegExp;
+      /** Optional conditional function that accepts the root Dashboard Vuex store getters and returns true if the group should be ignored */
+      condition?: (getters: any) => boolean;
+    }[]
+  }
+
+  /**
+   * Whether the product can be removed by users (default: false — products are built-in/not removable unless explicitly set to true)
+   */
+  removable?: boolean;
+
+    /**
+   * Leaving these here for completeness but I don't think these should be advertised as useable to plugin creators.
+   */
+  // ifHaveVerb: string | RegExp;
+  // supportRoute: string;
+  // typeStoreMap: string;
+};