@vitessce/vit-s 2.0.2 → 2.0.3

package/src/view-config-utils.js

@@ -0,0 +1,315 @@
+/* eslint-disable no-plusplus */
+/* eslint-disable camelcase */
+import difference from 'lodash/difference';
+import cloneDeep from 'lodash/cloneDeep';
+import { getNextScope } from '@vitessce/utils';
+import {
+  AUTO_INDEPENDENT_COORDINATION_TYPES,
+} from '@vitessce/constants-internal';
+import { getViewTypes } from './component-registry';
+import {
+  getComponentCoordinationTypes,
+  getDefaultCoordinationValues,
+  getCoordinationTypes,
+  getFileTypes,
+  getJointFileTypes,
+} from './plugins';
+import { SCHEMA_HANDLERS } from './view-config-versions';
+
+/**
+ * Get a list of all unique scope names for a
+ * particular coordination type, which exist in
+ * a particular view config.
+ * @param {object} config A view config object.
+ * @param {string} coordinationType A coordination type,
+ * for example 'spatialZoom' or 'dataset'.
+ * @returns {string[]} Array of existing coordination scope names.
+ */
+export function getExistingScopesForCoordinationType(config, coordinationType) {
+  const spaceScopes = Object.keys(config?.coordinationSpace?.[coordinationType] || {});
+  const componentScopes = config.layout.map(c => c.coordinationScopes?.[coordinationType]);
+  return Array.from(new Set([...spaceScopes, ...componentScopes]));
+}
+
+/**
+ * Give each component the same scope name for this coordination type.
+ * @param {object} config A view config object.
+ * @param {string} coordinationType A coordination type,
+ * for example 'spatialZoom' or 'dataset'.
+ * @param {*} scopeValue The initial value for the coordination scope,
+ * to set in the coordination space.
+ * @returns {object} The new view config.
+ */
+function coordinateComponentsTogether(config, coordinationType, scopeValue) {
+  const componentCoordinationTypes = getComponentCoordinationTypes();
+  const scopeName = getNextScope(getExistingScopesForCoordinationType(config, coordinationType));
+  const newConfig = {
+    ...config,
+    coordinationSpace: {
+      ...config.coordinationSpace,
+      [coordinationType]: {
+        ...config?.coordinationSpace?.[coordinationType],
+        // Add the new scope name and value to the coordination space.
+        [scopeName]: scopeValue,
+      },
+    },
+    layout: config.layout.map(component => ({
+      ...component,
+      coordinationScopes: {
+        ...component.coordinationScopes,
+        // Only set the coordination scope if this component uses this coordination type,
+        // and the component is missing a coordination scope for this coordination type.
+        ...((
+          componentCoordinationTypes[component.component].includes(coordinationType)
+          && !component.coordinationScopes?.[coordinationType]
+        ) ? {
+          // Only set the new scope name if the scope name
+          // for this component and coordination type is currently undefined.
+            [coordinationType]: scopeName,
+          } : {}),
+      },
+    })),
+  };
+  return newConfig;
+}
+
+/**
+ * Give each component a different scope name for this coordination type.
+ * @param {object} config A view config object.
+ * @param {string} coordinationType A coordination type,
+ * for example 'spatialZoom' or 'dataset'.
+ * @param {*} scopeValue The initial value for the coordination scope,
+ * to set in the coordination space.
+ * @returns {object} The new view config.
+ */
+function coordinateComponentsIndependent(config, coordinationType, scopeValue) {
+  const componentCoordinationTypes = getComponentCoordinationTypes();
+  const newConfig = {
+    ...config,
+    layout: [...config.layout],
+  };
+  const newScopes = {};
+  newConfig.layout.forEach((component, i) => {
+    // Only set the coordination scope if this component uses this coordination type,
+    // and the component is missing a coordination scope for this coordination type.
+    if (componentCoordinationTypes[component.component].includes(coordinationType)
+      && !component.coordinationScopes?.[coordinationType]
+    ) {
+      const scopeName = getNextScope([
+        ...getExistingScopesForCoordinationType(config, coordinationType),
+        ...Object.keys(newScopes),
+      ]);
+      newScopes[scopeName] = scopeValue;
+      newConfig.layout[i] = {
+        ...component,
+        coordinationScopes: {
+          ...component.coordinationScopes,
+          [coordinationType]: scopeName,
+        },
+      };
+    }
+  });
+  newConfig.coordinationSpace = {
+    ...newConfig.coordinationSpace,
+    [coordinationType]: {
+      ...newConfig.coordinationSpace[coordinationType],
+      // Add the new scope name and value to the coordination space.
+      ...newScopes,
+    },
+  };
+  return newConfig;
+}
+
+function initializeAuto(config) {
+  let newConfig = config;
+  const { layout, datasets } = newConfig;
+
+  const componentCoordinationTypes = getComponentCoordinationTypes();
+  const defaultCoordinationValues = getDefaultCoordinationValues();
+  const coordinationTypes = getCoordinationTypes();
+
+  // For each coordination type, check whether it requires initialization.
+  coordinationTypes.forEach((coordinationType) => {
+    // A coordination type requires coordination if at least one component is missing
+    // a (coordination type, coordination scope) tuple.
+    // Components may only use a subset of all coordination types.
+    const requiresCoordination = !layout
+      .every(c => (
+        (!componentCoordinationTypes[c.component].includes(coordinationType))
+                || c.coordinationScopes?.[coordinationType]
+      ));
+    if (requiresCoordination) {
+      // Note that the default value may be undefined.
+      let defaultValue = defaultCoordinationValues[coordinationType];
+      // Check whether this is the special 'dataset' coordination type.
+      if (coordinationType === 'dataset' && datasets.length >= 1) {
+        // Use the first dataset ID as the default
+        // if there is at least one dataset.
+        defaultValue = datasets[0].uid;
+      }
+      // Use the list of "independent" coordination types
+      // to determine whether a particular coordination type
+      // should be initialized to
+      // a unique scope for every component ("independent")
+      // vs. the same scope for every component ("together").
+      if (AUTO_INDEPENDENT_COORDINATION_TYPES.includes(coordinationType)) {
+        newConfig = coordinateComponentsIndependent(newConfig, coordinationType, defaultValue);
+      } else {
+        newConfig = coordinateComponentsTogether(newConfig, coordinationType, defaultValue);
+      }
+    }
+  });
+
+  return newConfig;
+}
+
+export function checkTypes(config) {
+  // Add a log message when there are additionalProperties in the coordination space that
+  // do not appear in the view config JSON schema,
+  // with a note that this indicates either a mistake or custom coordination type usage.
+  const coordinationTypesInConfig = Object.keys(config.coordinationSpace || {});
+  const allCoordinationTypes = getCoordinationTypes();
+  const unknownCoordinationTypes = difference(coordinationTypesInConfig, allCoordinationTypes);
+  if (unknownCoordinationTypes.length > 0) {
+    return [false, `The following coordination types are not recognized: [${unknownCoordinationTypes}].\nIf these are plugin coordination types, ensure that they have been properly registered.`];
+  }
+  // Add a log message when there are views in the layout that are neither
+  // core views nor registered plugin views.
+  const viewTypesInConfig = config.layout.map(c => c.component);
+  const allViewTypes = getViewTypes();
+  const unknownViewTypes = difference(viewTypesInConfig, allViewTypes);
+  if (unknownViewTypes.length > 0) {
+    return [false, `The following view types are not recognized: [${unknownViewTypes}].\nIf these are plugin view types, ensure that they have been properly registered.`];
+  }
+  // Add a log message when there are file definitions with neither
+  // core nor registered plugin file types.
+  const fileTypesInConfig = config.datasets.flatMap(d => d.files.map(f => f.fileType));
+  const allFileTypes = getFileTypes();
+  const unknownFileTypes = difference(fileTypesInConfig, allFileTypes);
+  if (unknownFileTypes.length > 0) {
+    return [false, `The following file types are not recognized: [${unknownFileTypes}].\nIf these are plugin file types, ensure that they have been properly registered.`];
+  }
+  return [true, 'All view types, coordination types, and file types that appear in the view config are recognized.'];
+}
+
+/**
+ * Assign unique ids for view definitions where
+ * they are missing a value for the uid property
+ * in layout[].uid.
+ * @param {object} config The view config
+ * @returns The updated view config.
+ */
+function assignViewUids(config) {
+  const { layout } = config;
+  const usedIds = layout.map(view => view.uid);
+  layout.forEach((view, i) => {
+    // Assign uids for views where they are not present.
+    if (!view.uid) {
+      const nextUid = getNextScope(usedIds);
+      layout[i].uid = nextUid;
+      usedIds.push(nextUid);
+    }
+  });
+  return {
+    ...config,
+    layout,
+  };
+}
+
+/**
+ * Expand convenience file definitions. Each convenience file
+ * definition expansion function takes in one file definition and
+ * returns an array of file definitions. Not performed recursively.
+ * @param {object} config The view config containing collapsed
+ * convenience file types.
+ * @returns The view config containing expanded minimal file types.
+ */
+function expandConvenienceFileDefs(config) {
+  const convenienceFileTypes = getJointFileTypes();
+  const { datasets: currDatasets } = config;
+  const datasets = cloneDeep(currDatasets);
+  currDatasets.forEach((dataset, i) => {
+    const { files = [] } = dataset;
+    let newFiles = [];
+    files.forEach((fileDef) => {
+      const { fileType } = fileDef;
+      const expansionFunc = convenienceFileTypes[fileType];
+      if (expansionFunc && typeof expansionFunc === 'function') {
+        // This was a convenience file type, so expand it.
+        const expandedFileDefs = expansionFunc(fileDef);
+        newFiles = newFiles.concat(expandedFileDefs);
+      } else {
+        // This was not a convenience file type,
+        // so keep it in the files array as-is.
+        newFiles.push(fileDef);
+      }
+    });
+    datasets[i].files = newFiles;
+  });
+  return {
+    ...config,
+    datasets,
+  };
+}
+
+/**
+ * Initialize the view config:
+ * - Fill in missing coordination objects with default values.
+ * - Fill in missing component coordination scope mappings.
+ *   based on the `initStrategy` specified in the view config.
+ * - Fill in missing view uid values.
+ * - Expand convenience file types.
+ * Should be "stable": if run on the same view config twice, the return value the second
+ * time should be identical to the return value the first time.
+ * @param {object} config The view config prop.
+ * @returns The initialized view config.
+ */
+export function initialize(config) {
+  let newConfig = cloneDeep(config);
+  if (newConfig.initStrategy === 'auto') {
+    newConfig = initializeAuto(config);
+  }
+  newConfig = expandConvenienceFileDefs(newConfig);
+  return assignViewUids(newConfig);
+}
+
+export function upgradeAndValidate(oldConfig, onConfigUpgrade = null) {
+  // oldConfig object must have a `version` property.
+  let nextConfig = oldConfig;
+  let fromVersion;
+  let upgradeFunction; let
+    validateFunction;
+
+  do {
+    fromVersion = nextConfig.version;
+
+    if (!Object.keys(SCHEMA_HANDLERS).includes(fromVersion)) {
+      return [{
+        title: 'Config validation failed',
+        preformatted: 'Unknown config version.',
+      }, false];
+    }
+
+    [validateFunction, upgradeFunction] = SCHEMA_HANDLERS[fromVersion];
+
+    // Validate under the legacy schema before upgrading.
+    const validLegacy = validateFunction(nextConfig);
+    if (!validLegacy) {
+      const failureReason = JSON.stringify(validateFunction.errors, null, 2);
+      return [{
+        title: 'Config validation failed',
+        preformatted: failureReason,
+      }, false];
+    }
+
+    if (upgradeFunction) {
+      const prevConfig = nextConfig;
+      nextConfig = upgradeFunction(nextConfig);
+      if (onConfigUpgrade) {
+        onConfigUpgrade(prevConfig, nextConfig);
+      }
+    }
+  } while (upgradeFunction);
+
+  return [nextConfig, true];
+}