Allow UI to initialize to old interface (backport #3322)

common/api/appui-react.api.md

@@ -6779,10 +6779,10 @@ export class UiFramework {
     static getWidgetOpacity(): number;
     // @alpha (undocumented)
     static get hideIsolateEmphasizeActionHandler(): HideIsolateEmphasizeActionHandler;
-    static initialize(store: Store<any> | undefined, frameworkStateKey?: string): Promise<void>;
+    static initialize(store: Store<any> | undefined, frameworkStateKey?: string, startInUi1Mode?: boolean): Promise<void>;
     static get initialized(): boolean;
     // @internal
-    static initializeEx(store: Store<any> | undefined, frameworkStateKey?: string): Promise<void>;
+    static initializeEx(store: Store<any> | undefined, frameworkStateKey?: string, startInUi1Mode?: boolean): Promise<void>;
     static initializeStateFromUserSettingsProviders(immediateSync?: boolean): Promise<void>;
     // @alpha
     static get isContextMenuOpen(): boolean;

common/changes/@itwin/appui-react/master_2022-03-09-13-16.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/appui-react",
+      "comment": "Allow initial UI version to be set when UIFramework is initialized.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/appui-react"
+}

test-apps/ui-test-app/src/frontend/index.tsx

@@ -85,6 +85,13 @@ export enum SampleAppUiActionId {
   setInitialViewIds = "sampleapp:setInitialViewIds",
 }
 
+/* ----------------------------------------------------------------------------
+* The following variable is used to test initializing UiFramework to use UI 1.0
+* and using that initial value in ui-test-app. By default UiFramework initializes
+* the Redux state to UI 2.0 mode.
+----------------------------------------------------------------------------- */
+const useUi1Mode = false;
+
 export interface SampleAppState {
   testProperty: string;
   animationViewId: string;
@@ -260,7 +267,7 @@ export class SampleAppIModelApp {
   }
 
   public static async initialize() {
-    await UiFramework.initialize(undefined);
+    await UiFramework.initialize(undefined, undefined, useUi1Mode);
 
     // initialize Presentation
     await Presentation.initialize({
@@ -323,16 +330,19 @@ export class SampleAppIModelApp {
 
     // Create and register the AppUiSettings instance to provide default for ui settings in Redux store
     const lastTheme = (window.localStorage && window.localStorage.getItem("uifw:defaultTheme")) ?? SYSTEM_PREFERRED_COLOR_THEME;
-    const defaults: InitialAppUiSettings = {
-      colorTheme: lastTheme ?? SYSTEM_PREFERRED_COLOR_THEME,
-      dragInteraction: false,
-      frameworkVersion: "2",
-      widgetOpacity: 0.8,
-      showWidgetIcon: true,
-    };
-
-    // initialize any settings providers that may need to have defaults set by iModelApp
-    UiFramework.registerUserSettingsProvider(new AppUiSettings(defaults));
+    if (!useUi1Mode) {
+      const defaults: InitialAppUiSettings = {
+        colorTheme: lastTheme ?? SYSTEM_PREFERRED_COLOR_THEME,
+        dragInteraction: false,
+        frameworkVersion: "2",
+        widgetOpacity: 0.8,
+        showWidgetIcon: true };
+
+      // initialize any settings providers that may need to have defaults set by iModelApp
+      UiFramework.registerUserSettingsProvider(new AppUiSettings(defaults));
+    } else {
+      window.localStorage.removeItem("AppUiSettings.FrameworkVersion");
+    }
 
     UiFramework.useDefaultPopoutUrl = true;
 

ui/appui-react/src/appui-react/UiFramework.ts

@@ -132,19 +132,21 @@ export class UiFramework {
    * Called by the application to initialize the UiFramework. Also initializes UIIModelComponents, UiComponents, UiCore.
    * @param store The single Redux store created by the host application. If this is `undefined` then it is assumed that the [[StateManager]] is being used to provide the Redux store.
    * @param frameworkStateKey The name of the key used by the app when adding the UiFramework state into the Redux store. If not defined "frameworkState" is assumed. This value is ignored if [[StateManager]] is being used. The StateManager use "frameworkState".
+   * @param startInUi1Mode Used for legacy applications to start up in the deprecated UI 1 mode. This should not set by newer applications.
    */
-  public static async initialize(store: Store<any> | undefined, frameworkStateKey?: string): Promise<void> {
-    return this.initializeEx(store, frameworkStateKey);
+  public static async initialize(store: Store<any> | undefined, frameworkStateKey?: string, startInUi1Mode?: boolean): Promise<void> {
+    return this.initializeEx(store, frameworkStateKey, startInUi1Mode);
   }
 
   /**
    * Called by the application to initialize the UiFramework. Also initializes UIIModelComponents, UiComponents, UiCore.
    * @param store The single Redux store created by the host application. If this is `undefined` then it is assumed that the [[StateManager]] is being used to provide the Redux store.
    * @param frameworkStateKey The name of the key used by the app when adding the UiFramework state into the Redux store. If not defined "frameworkState" is assumed. This value is ignored if [[StateManager]] is being used. The StateManager use "frameworkState".
+   * @param startInUi1Mode Used for legacy applications to start up in the deprecated UI 1 mode. This should not set by newer applications.
    *
    * @internal
    */
-  public static async initializeEx(store: Store<any> | undefined, frameworkStateKey?: string): Promise<void> {
+  public static async initializeEx(store: Store<any> | undefined, frameworkStateKey?: string, startInUi1Mode?: boolean): Promise<void> {
     if (UiFramework._initialized) {
       Logger.logInfo(UiFramework.loggerCategory(UiFramework), `UiFramework.initialize already called`);
       return;
@@ -160,6 +162,9 @@ export class UiFramework {
     if (frameworkStateKey && store)
       UiFramework._frameworkStateKeyInStore = frameworkStateKey;
 
+    if (startInUi1Mode)
+      UiFramework.store.dispatch({ type: ConfigurableUiActionId.SetFrameworkVersion, payload: "1" });
+
     // set up namespace and register all tools from package
     const frameworkNamespace = IModelApp.localization?.registerNamespace(UiFramework.localizationNamespace);
     [

ui/appui-react/src/test/UiFramework.test.ts

@@ -35,13 +35,27 @@ describe("UiFramework localStorage Wrapper", () => {
   });
 
   describe("UiFramework basic Initialization", () => {
-    it("should initialize default StateManager", async () => {
+    it("should initialize redux to UI 2", async () => {
       await UiFramework.initialize(undefined);
-      const uiVersion = "2";
+      expect(UiFramework.uiVersion).to.eql("2");
+      UiFramework.terminate();
+    });
+
+    it("should allow initialize to UI 1", async () => {
+      await UiFramework.initialize(undefined, undefined, true);
+      expect(UiFramework.uiVersion).to.eql("1");
+      UiFramework.terminate();
+    });
+
+    it("should initialize default StateManager to 2 and change to 1", async () => {
+      await UiFramework.initialize(undefined);
+      expect(UiFramework.uiVersion).to.eql("2");
+      const uiVersion = "1";
       UiFramework.setUiVersion(uiVersion);
       expect(UiFramework.uiVersion).to.eql(uiVersion);
       UiFramework.terminate();
     });
+
   });
 
   describe("UiFramework", () => {