scope class names per version (#2106)

Changes the prefix used for internal class names to include the exact package version, with the dots stripped out. (Previously, the prefix only included the number "3")

.changeset/nine-bees-peel.md

@@ -0,0 +1,5 @@
+---
+'@itwin/itwinui-react': minor
+---
+
+All internal CSS class prefixes have been changed to prevent style conflicts across minor versions. While this is not considered a breaking change according to our [support policy](https://github.com/iTwin/iTwinUI/wiki/Support-policy), this change might affect you if you ignore our pleas to not rely on these internal class names. The recommendation is to pass your own custom `className` through props.

packages/itwinui-react/src/core/ThemeProvider/ThemeProvider.tsx

@@ -25,6 +25,9 @@ import type { PolymorphicForwardRefComponent } from '../../utils/index.js';
 import { ThemeContext } from './ThemeContext.js';
 import { ToastProvider, Toaster } from '../Toast/Toaster.js';
 import { atom } from 'jotai';
+import { meta } from '../../utils/meta.js';
+
+const versionWithoutDots = meta.version.replace(/\./g, '');
 
 // ----------------------------------------------------------------------------
 
@@ -383,7 +386,11 @@ const PortaledToaster = ({ target }: { target?: HTMLElement }) => {
 const FallbackStyles = ({ root }: { root: HTMLElement }) => {
   useLayoutEffect(() => {
     // bail if styles are already loaded
-    if (getComputedStyle(root).getPropertyValue('--_iui-v3-loaded') === 'yes') {
+    if (
+      getComputedStyle(root).getPropertyValue(
+        `--_iui-v${versionWithoutDots}`,
+      ) === 'yes'
+    ) {
       return;
     }
 

packages/itwinui-react/src/styles.js/index.mjs

@@ -14,7 +14,7 @@ const styles = new Proxy(
   {
     get(_, prop) {
       if (typeof prop === 'string' && prop.startsWith('iui-')) {
-        return prop.replace('iui-', '_iui3-');
+        return prop.replace('iui-', `_iui${version.replace(/\./g, '')}-`);
       }
     },
     has(_, prop) {

packages/itwinui-react/src/styles.js/styles.module.css

@@ -8,12 +8,6 @@
 @import '@itwin/itwinui-variables' layer(itwinui.v3);
 @import '@itwin/itwinui-css';
 
-@layer itwinui.v3 {
-  .iui-root {
-    --_iui-v3-loaded: yes;
-  }
-}
-
 @layer itwinui {
   .iui-root * {
     /* When --_iui-width is set, inline-size will use it, otherwise it will be automatically reverted. */

packages/itwinui-react/src/styles.js/vite.config.mjs

@@ -6,9 +6,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defineConfig } from 'vite';
+import { version } from '../../package.json';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+const versionWithoutDots = version.replace(/\./g, '');
+
 // https://vitejs.dev/config/
 export default defineConfig({
   build: {
@@ -43,32 +46,48 @@ export default defineConfig({
     modules: {
       // TODO: use proper hash in v4
       generateScopedName: (name) => {
-        return `_iui3-${name.replace('iui-', '')}`;
+        return `_iui${versionWithoutDots}-${name.replace('iui-', '')}`;
       },
     },
     postcss: {
-      plugins: [
-        Object.assign(
-          () => ({
-            postcssPlugin: true,
-            Rule(rule) {
-              if (
-                rule.type === 'rule' &&
-                rule.selector?.startsWith(':where([data-iui-theme')
-              ) {
-                rule.selector = `:where(.iui-root)${rule.selector}`;
-              }
-            },
-          }),
-          { postcss: true },
-        ),
-      ],
+      plugins: [postcssAddIuiRoot(), postcssAddIuiVersion()],
     },
   },
 });
 
 // ----------------------------------------------------------------------------
 
+function postcssAddIuiRoot() {
+  return Object.assign(
+    () => ({
+      postcssPlugin: true,
+      Rule(rule) {
+        if (
+          rule.type === 'rule' &&
+          rule.selector?.startsWith(':where([data-iui-theme')
+        ) {
+          rule.selector = `:where(.iui-root)${rule.selector}`;
+        }
+      },
+    }),
+    { postcss: true, postcssPlugin: 'add-iui-root' },
+  );
+}
+
+function postcssAddIuiVersion() {
+  return Object.assign(
+    () => ({
+      postcssPlugin: true,
+      Once(root) {
+        root.append(`:where(:root) { --_iui-v${versionWithoutDots}: yes; }`);
+      },
+    }),
+    { postcss: true, postcssPlugin: 'add-iui-version' },
+  );
+}
+
+// ----------------------------------------------------------------------------
+
 const root = path.join(__dirname, '..', '..');
 const srcDir = path.join(root, 'src');
 const distDir = path.join(srcDir, 'styles.js', 'dist');