#9137: types and migrations for mod variable declaration section (1/3)

src/activation/mapModComponentDefinitionToActivatedModComponent.ts

@@ -27,6 +27,7 @@ import type { Deployment } from "@/types/contract";
 import type { OptionsArgs } from "@/types/runtimeTypes";
 import type { IntegrationDependency } from "@/integrations/integrationTypes";
 import { nowTimestamp } from "@/utils/timeUtils";
+import { emptyModVariablesDefinitionFactory } from "@/utils/modUtils";
 
 export type ActivateModComponentParam = {
   /**
@@ -75,6 +76,8 @@ export function mapModComponentDefinitionToActivatedModComponent<
     // Definitions are pushed down into the mod components. That's OK because `resolveDefinitions` determines
     // uniqueness based on the content of the definition. Therefore, bricks will be re-used as necessary
     definitions: modDefinition.definitions ?? {},
+    // Mod variable definitions/declarations are pushed down into the mod components.
+    variables: modDefinition.variables ?? emptyModVariablesDefinitionFactory(),
     optionsArgs,
     label: modComponentDefinition.label,
     extensionPointId: modComponentDefinition.id,

src/components/fields/schemaFields/integrations/integrationDependencyFieldUtils.test.ts

@@ -31,6 +31,7 @@ import { validateOutputKey } from "@/runtime/runtimeTypes";
 import { toExpression } from "@/utils/expressionUtils";
 import { normalizeAvailability } from "@/bricks/available";
 import { StarterBrickTypes } from "@/types/starterBrickTypes";
+import { emptyModVariablesDefinitionFactory } from "@/utils/modUtils";
 
 describe("selectVariables", () => {
   test("selects nothing when no services used", () => {
@@ -222,6 +223,7 @@ describe("selectVariables", () => {
       ],
       permissions: emptyPermissionsFactory(),
       optionsArgs: {},
+      variablesDefinition: emptyModVariablesDefinitionFactory(),
       modMetadata: undefined,
       modComponent: {
         brickPipeline: [

src/pageEditor/starterBricks/base.ts

@@ -58,7 +58,10 @@ import {
   type BaseFormState,
   type SingleLayerReaderConfig,
 } from "@/pageEditor/store/editor/baseFormStateTypes";
-import { emptyModOptionsDefinitionFactory } from "@/utils/modUtils";
+import {
+  emptyModOptionsDefinitionFactory,
+  emptyModVariablesDefinitionFactory,
+} from "@/utils/modUtils";
 import {
   type Availability,
   type NormalizedAvailability,
@@ -123,6 +126,7 @@ export function baseFromModComponent<T extends StarterBrickType>(
   | "integrationDependencies"
   | "permissions"
   | "optionsArgs"
+  | "variablesDefinition"
   | "modMetadata"
 > & { type: T } {
   return {
@@ -134,6 +138,8 @@ export function baseFromModComponent<T extends StarterBrickType>(
     integrationDependencies: config.integrationDependencies ?? [],
     permissions: config.permissions ?? {},
     optionsArgs: config.optionsArgs ?? {},
+    variablesDefinition:
+      config.variables ?? emptyModVariablesDefinitionFactory(),
     type,
     modMetadata: config._recipe,
   };
@@ -173,6 +179,7 @@ export function baseSelectModComponent({
   uuid,
   label,
   optionsArgs,
+  variablesDefinition,
   integrationDependencies,
   permissions,
   starterBrick,
@@ -187,6 +194,7 @@ export function baseSelectModComponent({
   | "integrationDependencies"
   | "permissions"
   | "optionsArgs"
+  | "variables"
 > {
   return {
     id: uuid,
@@ -197,6 +205,7 @@ export function baseSelectModComponent({
     integrationDependencies,
     permissions,
     optionsArgs,
+    variables: variablesDefinition,
   };
 }
 
@@ -209,6 +218,7 @@ export function makeInitialBaseState(
     integrationDependencies: [],
     permissions: emptyPermissionsFactory(),
     optionsArgs: {},
+    variablesDefinition: emptyModVariablesDefinitionFactory(),
     modComponent: {
       brickPipeline: [],
     },

src/pageEditor/store/editor/baseFormStateTypes.ts

@@ -26,7 +26,10 @@ import { type UUID } from "@/types/stringTypes";
 import { type StarterBrickType } from "@/types/starterBrickTypes";
 import { type Permissions } from "webextension-polyfill";
 import { type ModComponentBase } from "@/types/modComponentTypes";
-import { type ModOptionsDefinition } from "@/types/modDefinitionTypes";
+import {
+  type ModOptionsDefinition,
+  type ModVariablesDefinition,
+} from "@/types/modDefinitionTypes";
 import { type BrickPipeline } from "@/bricks/types";
 import { type Metadata, type RegistryId } from "@/types/registryTypes";
 import { type NormalizedAvailability } from "@/types/availabilityTypes";
@@ -71,6 +74,7 @@ export type BaseModComponentState = BaseModComponentStateV2;
 
 /**
  * @deprecated - Do not use versioned state types directly
+ * @see BaseFormState
  */
 export interface BaseFormStateV1<
   TModComponent extends BaseModComponentStateV1 = BaseModComponentStateV1,
@@ -143,6 +147,7 @@ export interface BaseFormStateV1<
 
 /**
  * @deprecated - Do not use versioned state types directly
+ * @see BaseFormState
  */
 export type BaseFormStateV2<
   TModComponent extends BaseModComponentStateV1 = BaseModComponentStateV1,
@@ -159,6 +164,7 @@ export type BaseFormStateV2<
 
 /**
  * @deprecated - Do not use versioned state types directly
+ * @see BaseFormState
  */
 export type BaseFormStateV3<
   TModComponent extends BaseModComponentStateV2 = BaseModComponentStateV2,
@@ -194,6 +200,7 @@ export type BaseFormStateV3<
 
 /**
  * @deprecated - Do not use versioned state types directly
+ * @see BaseFormState
  */
 export type BaseFormStateV4<
   TModComponent extends BaseModComponentStateV2 = BaseModComponentStateV2,
@@ -207,15 +214,33 @@ export type BaseFormStateV4<
   "type"
 >;
 
+/**
+ * Base form state version that introduces a variablesDefinition section for declaring mod variables.
+ * @deprecated - Do not use versioned state types directly
+ * @see BaseFormState
+ * @since 2.1.2
+ */
+export type BaseFormStateV5<
+  TModComponent extends BaseModComponentState = BaseModComponentState,
+  TStarterBrick extends BaseStarterBrickState = BaseStarterBrickState,
+> = BaseFormStateV4<TModComponent, TStarterBrick> & {
+  /**
+   * The mod variable definitions/declarations
+   * @see ModDefinition.variables
+   * @since 2.1.2
+   */
+  variablesDefinition: ModVariablesDefinition;
+};
+
 export type BaseFormState<
   TModComponent extends BaseModComponentState = BaseModComponentState,
   TStarterBrick extends BaseStarterBrickState = BaseStarterBrickState,
 > = Except<
-  BaseFormStateV4<TModComponent, TStarterBrick>,
+  // On migration, re-point this type to the most recent BaseFormStateV<N> type name
+  BaseFormStateV5<TModComponent, TStarterBrick>,
+  // NOTE: this is not changing the type shape/structure. It's just cleaning up the type name/reference which makes
+  // types easier to work with for testing migrations.
   "integrationDependencies"
 > & {
-  /**
-   * Using the un-versioned type
-   */
   integrationDependencies: IntegrationDependency[];
 };

src/pageEditor/store/editor/editorSlice.ts

@@ -1039,7 +1039,7 @@ export const persistEditorConfig = {
   // Change the type of localStorage to our overridden version so that it can be exported
   // See: @/store/StorageInterface.ts
   storage: localStorage as StorageInterface,
-  version: 7,
+  version: 8,
   migrate: createMigrate(migrations, { debug: Boolean(process.env.DEBUG) }),
   blacklist: [
     "inserting",

src/pageEditor/store/editor/pageEditorTypes.ts

@@ -39,6 +39,7 @@ import {
   type BaseFormStateV2,
   type BaseFormStateV3,
   type BaseFormStateV4,
+  type BaseFormStateV5,
 } from "@/pageEditor/store/editor/baseFormStateTypes";
 
 export type AddBrickLocation = {
@@ -381,12 +382,38 @@ export type EditorStateV5 = Except<
  */
 export type EditorStateV6 = Except<EditorStateV5, "insertingStarterBrickType">;
 
-// Instead of maintaining old enums, just clearing data panel state on migration, see migrateEditorStateV5
+/**
+ * Version bump to account for changes in DataPanelTabKeys.
+ *
+ * Same type as EditorStateV6, but bumped because there's an associated migration to clear out the Data Panel UI state.
+ *
+ * @deprecated - Do not use versioned state types directly, exported for testing
+ * @see migrateEditorStateV6
+ * @see DataPanelTabKey
+ */
 export type EditorStateV7 = EditorStateV6;
 
-export type EditorState = Except<
+/**
+ * Version bump to account for variableDefinition property added in BaseFormState
+ *
+ * @deprecated - Do not use versioned state types directly, exported for testing
+ * @see migrateEditorStateV7
+ */
+export type EditorStateV8 = Except<
   EditorStateV7,
   "modComponentFormStates" | "deletedModComponentFormStatesByModId"
+> & {
+  modComponentFormStates: BaseFormStateV5[];
+  deletedModComponentFormStatesByModId: Record<string, BaseFormStateV5[]>;
+};
+
+export type EditorState = Except<
+  // On migration, re-point this type to the most recent EditorStateV<N> type name
+  EditorStateV8,
+  // Swap out any properties with versioned types for type references to the latest version.
+  // NOTE: this is not changing the type shape/structure. It's just cleaning up the type name/reference which makes
+  // types easier to work with for testing migrations.
+  "modComponentFormStates" | "deletedModComponentFormStatesByModId"
 > & {
   modComponentFormStates: ModComponentFormState[];
   deletedModComponentFormStatesByModId: Record<string, ModComponentFormState[]>;

src/store/editorMigrations.test.ts

@@ -23,6 +23,7 @@
   type EditorStateV5,
   type EditorStateV6,
   type EditorStateV7,
+  type EditorStateV8,
 } from "@/pageEditor/store/editor/pageEditorTypes";
 import { cloneDeep, mapValues, omit } from "lodash";
 import {
@@ -56,13 +57,15 @@
   migrateEditorStateV4,
   migrateEditorStateV5,
   migrateEditorStateV6,
+  migrateEditorStateV7,
 } from "@/store/editorMigrations";
 import { type FactoryConfig } from "cooky-cutter/dist/define";
 import { StarterBrickTypes } from "@/types/starterBrickTypes";
 import {
   FOUNDATION_NODE_ID,
   makeInitialBrickPipelineUIState,
 } from "@/pageEditor/store/editor/uiState";
+import { modComponentToFormState } from "@/pageEditor/starterBricks/adapter";
 
 const initialStateV1: EditorStateV1 & PersistedState = {
   selectionSeq: 0,
@@ -249,6 +252,40 @@
 const initialStateV7: EditorStateV7 & PersistedState =
   cloneDeep(initialStateV6);
 
+const initialStateV8: EditorStateV8 & PersistedState = {
+  selectionSeq: 0,
+  activeModComponentId: null,
+  activeModId: null,
+  expandedModId: null,
+  error: null,
+  beta: false,
+  modComponentFormStates: [],
+  knownEditableBrickIds: [],
+  dirty: {},
+  isBetaUI: false,
+  copiedBrick: undefined,
+  brickPipelineUIStateById: {},
+  dirtyModOptionsById: {},
+  dirtyModMetadataById: {},
+  visibleModalKey: null,
+  addBrickLocation: undefined,
+  keepLocalCopyOnCreateMod: false,
+  deletedModComponentFormStatesByModId: {},
+  availableActivatedModComponentIds: [],
+  isPendingAvailableActivatedModComponents: false,
+  availableDraftModComponentIds: [],
+  isPendingDraftModComponents: false,
+  isModListExpanded: true,
+  isDataPanelExpanded: true,
+  isDimensionsWarningDismissed: false,
+  isVariablePopoverVisible: false,
+  // Function under test does not handle updating the persistence, this is handled by redux-persist
+  _persist: {
+    version: 1,
+    rehydrated: false,
+  },
+};
+
 function unmigrateServices(
   integrationDependencies: IntegrationDependencyV2[] = [],
 ): IntegrationDependencyV1[] {
@@ -615,4 +652,16 @@
       );
     });
   });
+
+  describe("migrateEditorState V7 to V8", () => {
+    it("migrates empty state", () => {
+      expect(migrateEditorStateV7(initialStateV7)).toStrictEqual(
+        initialStateV8,
+      );
+    });
+
+    it("add variable definitions section", () => {
+      throw Error("Not implemented");
+    });
+  });
 });

src/store/editorMigrations.ts

@@ -22,6 +22,7 @@ import {
   type BaseFormStateV2,
   type BaseFormStateV3,
   type BaseFormStateV4,
+  type BaseFormStateV5,
   type BaseModComponentStateV1,
   type BaseModComponentStateV2,
 } from "@/pageEditor/store/editor/baseFormStateTypes";
@@ -30,19 +31,22 @@ import {
   type IntegrationDependencyV2,
 } from "@/integrations/integrationTypes";
 import {
+  type EditorState,
   type EditorStateV1,
   type EditorStateV2,
   type EditorStateV3,
   type EditorStateV4,
   type EditorStateV5,
   type EditorStateV6,
   type EditorStateV7,
+  type EditorStateV8,
 } from "@/pageEditor/store/editor/pageEditorTypes";
 import { type ModComponentFormState } from "@/pageEditor/starterBricks/formStateTypes";
 import { produce } from "immer";
 import { DataPanelTabKey } from "@/pageEditor/tabs/editTab/dataPanel/dataPanelTypes";
 import { makeInitialDataTabState } from "@/pageEditor/store/editor/uiState";
 import { type BrickConfigurationUIState } from "@/pageEditor/store/editor/uiStateTypes";
+import { emptyModVariablesDefinitionFactory } from "@/utils/modUtils";
 
 export const migrations: MigrationManifest = {
   // Redux-persist defaults to version: -1; Initialize to positive-1-indexed
@@ -55,6 +59,7 @@ export const migrations: MigrationManifest = {
   5: (state: EditorStateV4 & PersistedState) => migrateEditorStateV4(state),
   6: (state: EditorStateV5 & PersistedState) => migrateEditorStateV5(state),
   7: (state: EditorStateV6 & PersistedState) => migrateEditorStateV6(state),
+  8: (state: EditorStateV7 & PersistedState) => migrateEditorStateV7(state),
 };
 
 export function migrateIntegrationDependenciesV1toV2(
@@ -223,3 +228,24 @@ export function migrateEditorStateV6(
     }
   });
 }
+
+export function migrateEditorStateV7(
+  state: EditorStateV7 & PersistedState,
+): EditorStateV8 & PersistedState {
+  // Reset the Data Panel state using the current set of DataPanelTabKeys
+  return produce(state, (draft) => {
+    for (const formState of draft.modComponentFormStates) {
+      (formState as BaseFormStateV5).variablesDefinition =
+        emptyModVariablesDefinitionFactory();
+    }
+
+    for (const formStates of Object.values(
+      draft.deletedModComponentFormStatesByModId,
+    )) {
+      for (const formState of formStates) {
+        (formState as BaseFormStateV5).variablesDefinition =
+          emptyModVariablesDefinitionFactory();
+      }
+    }
+  }) as EditorState & PersistedState;
+}

src/testUtils/factories/pageEditorFactories.ts

@@ -56,6 +56,7 @@ import { type BaseModComponentState } from "@/pageEditor/store/editor/baseFormSt
 import { assertNotNullish } from "@/utils/nullishUtils";
 import { type Permissions } from "webextension-polyfill";
 import { validateOutputKey } from "@/runtime/runtimeTypes";
+import { emptyModVariablesDefinitionFactory } from "@/utils/modUtils";
 
 const baseModComponentStateFactory = define<BaseModComponentState>({
   brickPipeline: () => pipelineFactory(),
@@ -75,6 +76,7 @@ const internalFormStateFactory = define<InternalFormStateOverride>({
   uuid: uuidSequence,
   installed: true,
   optionsArgs: () => ({}) as OptionsArgs,
+  variablesDefinition: () => emptyModVariablesDefinitionFactory(),
   integrationDependencies(): IntegrationDependency[] {
     return [];
   },