fix(many): fix having the same DOM ids if there are multiple instances of InstUI, e.g. module federation

matyasf · matyasf · commit a0bb4d0a8d0f · 2025-03-31T16:11:37.000+02:00
Its fixed by moving the instance counter to the global object. Also the generation pattern is
altered slightly to work nicely with older versions of InstUI which do not use this new global
object

Fixes INSTUI-4484
diff --git a/docs/guides/accessing-the-dom.md b/docs/guides/accessing-the-dom.md
@@ -1,7 +1,7 @@
 ---
 title: Accessing the DOM
 category: Guides
-order: 4
+order: 5
 ---
 
 ## Accessing the DOM
diff --git a/docs/guides/color-system.md b/docs/guides/color-system.md
@@ -1,7 +1,7 @@
 ---
 title: Color System
 category: Guides
-order: 5
+order: 6
 ---
 
 ## Colors
diff --git a/docs/guides/focus-management.md b/docs/guides/focus-management.md
@@ -1,7 +1,7 @@
 ---
 title: Focus Management
 category: Guides
-order: 3
+order: 4
 ---
 
 ## The Focus Management Problem
diff --git a/docs/guides/module-federation.md b/docs/guides/module-federation.md
@@ -0,0 +1,25 @@
+---
+title: Module federation
+category: Guides
+order: 1
+---
+
+# Module federation
+
+InstUI supports [module federation](https://module-federation.io/) with some caveats. In a host app-guest app scenario, you have 2 choices depending on the version of InstUI you are using:
+
+### (Recommended) Host and guest app are using larger version than InstUI v10.14:
+
+- Both apps should use `canvasThemeLocal` or `canvasHighContrastThemeLocal` from the `@instructure/ui-themes` package when using themes. This means that `InstUISettingsProvider`'s theme prop cannot be left unset because it will default to `canvas`.
+- Apps cannot use `canvas.use()`, `canvasHighContrast.use()`, these do not exist in the local themes.
+
+### Host app is using InstUI v10.14 or earlier:
+
+- Guest app needs to use **larger** version than InstUI v10.14
+- Host app needs to import the `canvas`/`canvasHighContrast` theme before loading the guest app
+- Guest app must use `canvasThemeLocal` or `canvasHighContrastThemeLocal`. Guest app's `InstUISettingsProvider`'s `theme` prop cannot be left unset because it will default to `canvas`
+- Guest app cannot use `canvas.use()`, `canvasHighContrast.use()`, these do not exist in the local themes.
+
+> Overrides specified in global themes are not applied to local themes.
+
+You can check out a sample application on [Github](https://github.com/matyasf/module-federation-instui)
diff --git a/docs/guides/server-side-rendering.md b/docs/guides/server-side-rendering.md
@@ -1,7 +1,7 @@
 ---
 title: Server side rendering (SSR)
 category: Guides
-order: 1
+order: 2
 ---
 
 # SSR with Next.js
@@ -45,8 +45,7 @@ npm install @instructure/emotion @instructure/ui-react-utils
 
 - in your Next.js application create - if it does not already exist - a file named `_app.js` inside the `pages` directory. This is a special file in Next.js because it allows you to override/control component initialization. Read more about it in the [Next.js docs](https://nextjs.org/docs/advanced-features/custom-app).
 
-- then configure the `_app.js` so your component tree is wrapped with an `InstUISettingsProvider`
-- the important step is to call `generateInstanceCounterMap` on every request, so the server side instance tracking and browser side instance tracking stays in sync with each other:
+- then configure the `_app.js` so your component tree is wrapped with an `InstUISettingsProvider` component. This component is responsible for keeping track of component instances and generating deterministic `ids` for components.
 
 ```js
 ---
@@ -66,8 +65,7 @@ export default function MyApp(props) {
       <Head>
         <meta name="viewport" content="initial-scale=1, width=device-width" />
       </Head>
-                                               {/* This is the important step */}
-      <InstUISettingsProvider instanceCounterMap={generateInstanceCounterMap()}>
+      <InstUISettingsProvider>
         <Component {...pageProps} />
       </InstUISettingsProvider>
     </>
diff --git a/docs/guides/typography-system.md b/docs/guides/typography-system.md
@@ -1,7 +1,7 @@
 ---
 title: Typography
 category: Guides
-order: 8
+order: 9
 ---
 
 # Typography
diff --git a/docs/guides/using-theme-overrides.md b/docs/guides/using-theme-overrides.md
@@ -1,7 +1,7 @@
 ---
 title: Using theme overrides
 category: Guides
-order: 2
+order: 3
 ---
 
 ## Using theme overrides
diff --git a/packages/emotion/src/InstUISettingsProvider/index.tsx b/packages/emotion/src/InstUISettingsProvider/index.tsx
@@ -44,7 +44,11 @@ type InstUIProviderProps = {
   theme?: ThemeOrOverride
 
   /**
-   * A [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) which keeps track of specific InstUI components. (generally this is used for deterministic id generation for [SSR](/#server-side-rendering))
+   * @deprecated the `instanceCounterMap` prop is deprecated. You don't need to supply the
+   * `instanceCounterMap` to the component. It handles it internally.
+   *
+   * A [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) which keeps track of
+   * specific InstUI components. (generally this is used for deterministic id generation for [SSR](/#server-side-rendering))
    */
   instanceCounterMap?: DeterministicIdProviderValue
 } & (
@@ -57,14 +61,16 @@ type InstUIProviderProps = {
        */
       dir: 'ltr' | 'rtl'
       /**
-       *  Deprecated property, remove in 10.0.0
+       *  @deprecated remove in v11
+       *  The element type to render as
        */
       as?: AsElementType
     }
   | {
       dir?: never
       /**
-       *  Deprecated property, remove in 10.0.0
+       *  @deprecated remove in v11
+       *  The element type to render as
        */
       as?: never
     }
diff --git a/packages/ui-react-utils/src/DeterministicIdContext/DeterministicIdContext.ts b/packages/ui-react-utils/src/DeterministicIdContext/DeterministicIdContext.ts
@@ -22,9 +22,31 @@
  * SOFTWARE.
  */
 import React from 'react'
-import { generateInstanceCounterMap } from './generateInstanceCounterMap'
+import type { DeterministicIdProviderValue } from './DeterministicIdContextProvider'
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __INSTUI_GLOBAL_INSTANCE_COUNTER__: Map<string, number>
+}
+const instUIInstanceCounter = '__INSTUI_GLOBAL_INSTANCE_COUNTER__'
+
+/**
+ * Returns a global (window-level) instance counter map.
+ * This needs to be global so that IDs are unique across application instances,
+ * e.g. in module federation applications are loaded as a .js blob, this method
+ * makes sure that there are no duplicate IDs across instances.
+ */
+function generateInstanceCounterMap(): DeterministicIdProviderValue {
+  if (globalThis[instUIInstanceCounter]) {
+    return globalThis[instUIInstanceCounter]
+  }
+  const map = new Map<string, number>()
+  globalThis[instUIInstanceCounter] = map
+  return map
+}
 
 const defaultDeterministicIDMap = generateInstanceCounterMap()
+
 const DeterministicIdContext = React.createContext(defaultDeterministicIDMap)
 
 export { DeterministicIdContext, defaultDeterministicIDMap }
diff --git a/packages/ui-react-utils/src/DeterministicIdContext/DeterministicIdContextProvider.tsx b/packages/ui-react-utils/src/DeterministicIdContext/DeterministicIdContextProvider.tsx
@@ -29,6 +29,12 @@ import {
 
 type DeterministicIdProviderValue = Map<string, number>
 type DeterministicIdProviderProps = React.PropsWithChildren<{
+  /**
+   * @deprecated the `instanceCounterMap` prop is deprecated. You don't need to
+   * supply the `instanceCounterMap` to the component. It handles it internally.
+   * If you use this make sure that it generates unique IDs across app instances
+   * like in module federation.
+   */
   instanceCounterMap?: DeterministicIdProviderValue
 }>
 
@@ -44,7 +50,6 @@ type DeterministicIdProviderProps = React.PropsWithChildren<{
  * This is utility component for wrapping components with `DeterministicIdContext.Provider`
  * See detailed documentation about how to use it: [InstUISettingsProvider](/#InstUISettingsProvider)
  */
-
 const DeterministicIdContextProvider = ({
   children,
   instanceCounterMap = defaultDeterministicIDMap
diff --git a/packages/ui-react-utils/src/DeterministicIdContext/generateInstanceCounterMap.ts b/packages/ui-react-utils/src/DeterministicIdContext/generateInstanceCounterMap.ts
diff --git a/packages/ui-react-utils/src/DeterministicIdContext/index.ts b/packages/ui-react-utils/src/DeterministicIdContext/index.ts
@@ -22,7 +22,6 @@
  * SOFTWARE.
  */
 
-export { generateInstanceCounterMap } from './generateInstanceCounterMap'
 export { DeterministicIdContextProvider } from './DeterministicIdContextProvider'
 export { DeterministicIdContext } from './DeterministicIdContext'
 export { withDeterministicId } from './withDeterministicId'
diff --git a/packages/ui-react-utils/src/__new-tests__/DeterministicIdContext.test.tsx b/packages/ui-react-utils/src/__new-tests__/DeterministicIdContext.test.tsx
@@ -29,8 +29,7 @@ import '@testing-library/jest-dom'
 
 import {
   withDeterministicId,
-  DeterministicIdContextProvider,
-  generateInstanceCounterMap
+  DeterministicIdContextProvider
 } from '../DeterministicIdContext'
 import type { WithDeterministicIdProps } from '../DeterministicIdContext'
 
@@ -106,9 +105,7 @@ describe('DeterministicIdContext', () => {
   it('should generate unique ids with provider only', () => {
     const Wrapper = ({ children }: any) => {
       return (
-        <DeterministicIdContextProvider
-          instanceCounterMap={generateInstanceCounterMap()}
-        >
+        <DeterministicIdContextProvider>
           <div data-testid="wrapper">{children}</div>
         </DeterministicIdContextProvider>
       )
@@ -123,4 +120,21 @@ describe('DeterministicIdContext', () => {
 
     expect(uniqueIds(el)).toBe(true)
   })
+
+  it('should use a global object for ID counter', () => {
+    const instUIInstanceCounter = '__INSTUI_GLOBAL_INSTANCE_COUNTER__'
+    const counterValue = 345
+    globalThis[instUIInstanceCounter].set('TestComponent', counterValue)
+    render(
+      <div data-testid="test-components">
+        <TestComponent />
+        <TestComponent />
+        <TestComponent />
+        <TestComponent />
+        <TestComponent />
+      </div>
+    )
+    const instanceCounter = globalThis[instUIInstanceCounter]
+    expect(instanceCounter.get('TestComponent')).toBe(counterValue + 5)
+  })
 })
diff --git a/packages/ui-react-utils/src/index.ts b/packages/ui-react-utils/src/index.ts
@@ -39,7 +39,6 @@ export { safeCloneElement } from './safeCloneElement'
 export { windowMessageListener } from './windowMessageListener'
 export {
   DeterministicIdContext,
-  generateInstanceCounterMap,
   DeterministicIdContextProvider,
   withDeterministicId
 } from './DeterministicIdContext'
diff --git a/packages/ui-top-nav-bar/src/TopNavBar/utils/mapItemsForDrilldown.tsx b/packages/ui-top-nav-bar/src/TopNavBar/utils/mapItemsForDrilldown.tsx
@@ -26,10 +26,7 @@ import React, { Children } from 'react'
 
 import { warn } from '@instructure/console'
 import { generateId } from '@instructure/ui-utils'
-import {
-  matchComponentTypes,
-  generateInstanceCounterMap
-} from '@instructure/ui-react-utils'
+import { matchComponentTypes } from '@instructure/ui-react-utils'
 
 import { Drilldown } from '@instructure/ui-drilldown'
 import type {
@@ -62,7 +59,7 @@ const mapItemsForDrilldown = (
   const submenus: ItemMappedForDrilldownOption[] = []
   const { currentPageId, renderOptionContent } = options
 
-  const customPopoverIdMap = generateInstanceCounterMap()
+  const customPopoverIdMap = new Map<string, number>()
 
   Children.forEach(itemList, (item) => {
     if (!item || !matchComponentTypes(item, [TopNavBarItem])) return
diff --git a/packages/ui-utils/src/generateId.ts b/packages/ui-utils/src/generateId.ts
@@ -28,15 +28,15 @@
  * @param map - a Map<string, counter>, which counts how many times the given element/instance was rendered
  * @returns a string in a format `instanceName_intanceRenderedCount`: `Alert_4`
  */
-
 const generateId = (instanceName: string, map: Map<string, number>) => {
   if (!map.has(instanceName)) {
     map.set(instanceName, 0)
   } else {
     map.set(instanceName, map.get(instanceName)! + 1)
   }
-
-  return `${instanceName}_${map.get(instanceName!)}`
+  // Do not rename '___' to '_' it will cause name clash with InstUI v10.14.0
+  // or older
+  return `${instanceName}___${map.get(instanceName!)}`
 }
 
 export default generateId
diff --git a/regression-test/postcss.config.js b/regression-test/postcss.config.js
@@ -1,3 +1,27 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
 module.exports = {
   plugins: {
     tailwindcss: {},
