replace useTheme with internal useGlobals

.changeset/gorgeous-boxes-smell.md

@@ -0,0 +1,5 @@
+---
+'@itwin/itwinui-react': major
+---
+
+Removed the deprecated `useTheme` hook. `<ThemeProvider>` is now always required to be wrapped around all iTwinUI components.

CONTRIBUTING.md

@@ -118,8 +118,6 @@ If you are creating a new component, use this script:
 
 It ensures all needed imports are added and files are created.
 
-> Note: Every component needs to use `useTheme()` hook to ensure styling (theming) works fine. The `createComponent` script mentioned above adds it automatically.
-
 For a component named `Alert`, the `createComponent` script will add/modify the following files:
 
 - packages/itwinui-css/src/**alert/alert.scss**: framework-agnostic component styles

apps/storybook/.storybook/StoryWithDecorator.jsx

@@ -0,0 +1,26 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { useDarkMode } from 'storybook-dark-mode';
+import { ThemeProvider } from '@itwin/itwinui-react';
+
+export default function StoryWithDecorator(Story, context) {
+  const theme = useDarkMode() ? 'dark' : 'light';
+  const highContrast = context.globals.hc;
+
+  const background =
+    context.globals.backgrounds?.value ??
+    'var(--iui-color-background-backdrop)';
+
+  return (
+    <ThemeProvider
+      theme={theme}
+      themeOptions={{ highContrast, applyBackground: false }}
+      style={{ background }}
+    >
+      <Story />
+    </ThemeProvider>
+  );
+}

apps/storybook/.storybook/preview-body.html

@@ -0,0 +1,9 @@
+<style>
+  html, body {
+    padding: 0 !important;
+  }
+  .iui-root {
+    padding: 1rem;
+    height: 100svh;
+  }
+</style>

apps/storybook/.storybook/preview.js

@@ -2,25 +2,17 @@
  * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
-import { addons } from '@storybook/addons';
 import { themes } from '@storybook/theming';
-import React from 'react';
 import { lightTheme, darkTheme } from './itwinTheme';
-
-const channel = addons.getChannel();
-
-channel.on('DARK_MODE', (isDark) => updateTheme(isDark));
+import StoryWithDecorator from './StoryWithDecorator.jsx';
 
 const prefersDark = window.matchMedia?.('(prefers-color-scheme: dark)').matches;
 
-const updateTheme = (isDark) => {
-  document.body.dataset.iuiTheme = isDark ? 'dark' : 'light';
-};
-
 /** @type { import('@storybook/react').Preview } */
 export default {
   parameters: {
     darkMode: {
+      classTarget: '.iui-root',
       dark: { ...themes.dark, ...darkTheme },
       light: { ...themes.light, ...lightTheme },
     },
@@ -51,18 +43,5 @@ export default {
     },
   },
 
-  decorators: [
-    (Story, context) => {
-      const {
-        globals: { hc: highContrast },
-      } = context;
-
-      React.useEffect(() => {
-        document.body.classList.toggle('iui-root', true);
-        document.body.dataset.iuiContrast = highContrast ? 'high' : 'default';
-      }, [highContrast]);
-
-      return Story(); // builder-vite does not allow JSX here so we call Story as a function
-    },
-  ],
+  decorators: [StoryWithDecorator],
 };

apps/storybook/src/ColorPicker.stories.tsx

@@ -160,7 +160,6 @@ export const Advanced: Story<ColorPickerProps> = (args) => {
               />
             </ColorPicker>
           }
-          appendTo={() => document.body}
           visible={isOpen}
           placement='bottom-start'
         >
@@ -240,7 +239,6 @@ export const WithAlpha: Story<ColorPickerProps> = (args) => {
               />
             </ColorPicker>
           }
-          appendTo={() => document.body}
           visible={isOpen}
           placement='bottom-start'
         >

apps/storybook/src/Table.stories.tsx

@@ -35,7 +35,6 @@ import {
   Input,
   Radio,
   ProgressRadial,
-  useTheme,
   BaseFilter,
 } from '@itwin/itwinui-react';
 import { Story, Meta } from '@storybook/react';
@@ -2459,8 +2458,6 @@ export const CustomFilter: Story<Partial<TableProps>> = (args) => {
   );
 
   const CustomFilter = () => {
-    useTheme();
-
     const handleChange = (isChecked: boolean, filter: string) => {
       setFilter(isChecked ? filter : '');
       setIsLoading(true);

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

@@ -5,7 +5,7 @@
 import cx from 'classnames';
 import * as React from 'react';
 import '@itwin/itwinui-css/css/alert.css';
-import { useTheme, StatusIconMap, SvgCloseSmall } from '../utils/index.js';
+import { useGlobals, StatusIconMap, SvgCloseSmall } from '../utils/index.js';
 import type { CommonProps } from '../utils/props.js';
 
 export type AlertProps = {
@@ -65,7 +65,7 @@ export const Alert = (props: AlertProps) => {
     ...rest
   } = props;
 
-  useTheme();
+  useGlobals();
 
   const StatusIcon = StatusIconMap[type];
 

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

@@ -4,7 +4,7 @@
  *--------------------------------------------------------------------------------------------*/
 import cx from 'classnames';
 import * as React from 'react';
-import { useTheme } from '../utils/index.js';
+import { useGlobals } from '../utils/index.js';
 import type { CommonProps } from '../utils/index.js';
 import '@itwin/itwinui-css/css/avatar.css';
 
@@ -90,7 +90,7 @@ export const Avatar = (props: AvatarProps) => {
     ...rest
   } = props;
 
-  useTheme();
+  useGlobals();
 
   const statusTitles = { ...defaultStatusTitles, ...translatedStatusTitles };
 

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

@@ -4,7 +4,7 @@
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
 import cx from 'classnames';
-import { useTheme } from '../utils/index.js';
+import { useGlobals } from '../utils/index.js';
 import type { CommonProps } from '../utils/index.js';
 import '@itwin/itwinui-css/css/avatar.css';
 
@@ -87,7 +87,7 @@ export const AvatarGroup = (props: AvatarGroupProps) => {
   const childrenArray = React.Children.toArray(children);
   const childrenLength = childrenArray.length;
 
-  useTheme();
+  useGlobals();
 
   const getAvatarList = (count: number) => {
     return childrenArray.slice(0, count).map((child) =>

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

@@ -4,7 +4,7 @@
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
 import cx from 'classnames';
-import { useTheme } from '../utils/index.js';
+import { useGlobals } from '../utils/index.js';
 import '@itwin/itwinui-css/css/backdrop.css';
 
 export type BackdropProps = {
@@ -18,7 +18,7 @@ export type BackdropProps = {
 export const Backdrop = React.forwardRef<HTMLDivElement, BackdropProps>(
   (props, ref) => {
     const { isVisible = true, className, ...rest } = props;
-    useTheme();
+    useGlobals();
     return (
       <div
         className={cx(

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

@@ -4,7 +4,11 @@
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
 import cx from 'classnames';
-import { useTheme, isSoftBackground, SoftBackgrounds } from '../utils/index.js';
+import {
+  useGlobals,
+  isSoftBackground,
+  SoftBackgrounds,
+} from '../utils/index.js';
 import type { CommonProps } from '../utils/index.js';
 import type { AnyString } from '../utils/index.js';
 import '@itwin/itwinui-css/css/badge.css';
@@ -62,7 +66,7 @@ export type BadgeProps = {
 export const Badge = (props: BadgeProps) => {
   const { backgroundColor, style, className, children, ...rest } = props;
 
-  useTheme();
+  useGlobals();
 
   // choosing 'primary' status should result in data-iui-status equaling 'informational'
   const reducedBackgroundColor =

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

@@ -5,7 +5,7 @@
 import * as React from 'react';
 import cx from 'classnames';
 import {
-  useTheme,
+  useGlobals,
   useMergedRefs,
   useOverflow,
   SvgChevronRight,
@@ -121,7 +121,7 @@ export const Breadcrumbs = React.forwardRef(
       ...rest
     } = props;
 
-    useTheme();
+    useGlobals();
 
     const [overflowRef, visibleCount] = useOverflow(items);
     const refs = useMergedRefs(overflowRef, ref);

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

@@ -4,7 +4,7 @@
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
 import cx from 'classnames';
-import { useTheme, useOverflow, useMergedRefs } from '../utils/index.js';
+import { useGlobals, useOverflow, useMergedRefs } from '../utils/index.js';
 import '@itwin/itwinui-css/css/button.css';
 
 export type ButtonGroupProps = {
@@ -81,7 +81,7 @@ export const ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
       [children],
     );
 
-    useTheme();
+    useGlobals();
 
     const [overflowRef, visibleCount] = useOverflow(
       items,

packages/itwinui-react/src/core/Buttons/Button/Button.tsx

@@ -5,7 +5,7 @@
 import cx from 'classnames';
 import * as React from 'react';
 
-import { useTheme } from '../../utils/index.js';
+import { useGlobals } from '../../utils/index.js';
 import type {
   PolymorphicComponentProps,
   PolymorphicForwardRefComponent,
@@ -65,7 +65,7 @@ export const Button: ButtonComponent = React.forwardRef((props, ref) => {
     ...rest
   } = props;
 
-  useTheme();
+  useGlobals();
 
   return (
     <Element

packages/itwinui-react/src/core/Buttons/DropdownButton/DropdownButton.tsx

@@ -11,7 +11,7 @@ import type { DropdownMenuProps } from '../../DropdownMenu/index.js';
 import {
   SvgCaretDownSmall,
   SvgCaretUpSmall,
-  useTheme,
+  useGlobals,
   useMergedRefs,
 } from '../../utils/index.js';
 import '@itwin/itwinui-css/css/button.css';
@@ -56,7 +56,7 @@ export const DropdownButton = React.forwardRef(
       ...rest
     } = props;
 
-    useTheme();
+    useGlobals();
 
     const [isMenuOpen, setIsMenuOpen] = React.useState(false);
 

packages/itwinui-react/src/core/Buttons/IconButton/IconButton.tsx

@@ -4,7 +4,7 @@
  *--------------------------------------------------------------------------------------------*/
 import cx from 'classnames';
 import * as React from 'react';
-import { useTheme, VisuallyHidden, Popover } from '../../utils/index.js';
+import { useGlobals, VisuallyHidden, Popover } from '../../utils/index.js';
 import type { ButtonProps } from '../Button/index.js';
 import type { PolymorphicForwardRefComponent } from '../../utils/index.js';
 import '@itwin/itwinui-css/css/button.css';
@@ -48,7 +48,7 @@ export const IconButton: IconButtonComponent = React.forwardRef(
       ...rest
     } = props;
 
-    useTheme();
+    useGlobals();
 
     return (
       <IconButtonTooltip label={label}>

packages/itwinui-react/src/core/Buttons/IdeasButton/IdeasButton.tsx

@@ -3,7 +3,7 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
-import { SvgSmileyHappy, useTheme } from '../../utils/index.js';
+import { SvgSmileyHappy, useGlobals } from '../../utils/index.js';
 import { Button } from '../Button/index.js';
 
 export type IdeasButtonProps = {
@@ -26,7 +26,7 @@ export const IdeasButton = React.forwardRef(
   (props: IdeasButtonProps, ref: React.RefObject<HTMLButtonElement>) => {
     const { feedbackLabel = 'Feedback', onClick, ...rest } = props;
 
-    useTheme();
+    useGlobals();
 
     return (
       <Button

packages/itwinui-react/src/core/Buttons/SplitButton/SplitButton.tsx

@@ -12,7 +12,7 @@ import type { Placement } from 'tippy.js';
 import {
   SvgCaretDownSmall,
   SvgCaretUpSmall,
-  useTheme,
+  useGlobals,
 } from '../../utils/index.js';
 import type { PolymorphicForwardRefComponent } from '../../utils/index.js';
 import '@itwin/itwinui-css/css/button.css';
@@ -69,7 +69,7 @@ export const SplitButton: SplitButtonComponent = React.forwardRef(
       ...rest
     } = props;
 
-    useTheme();
+    useGlobals();
 
     const [isMenuOpen, setIsMenuOpen] = React.useState(false);
 

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

@@ -4,7 +4,7 @@
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
 import cx from 'classnames';
-import { getRandomValue, useMergedRefs, useTheme } from '../utils/index.js';
+import { getRandomValue, useMergedRefs, useGlobals } from '../utils/index.js';
 import '@itwin/itwinui-css/css/carousel.css';
 import { CarouselContext } from './CarouselContext.js';
 import { CarouselSlider } from './CarouselSlider.js';
@@ -59,7 +59,7 @@ export const Carousel = Object.assign(
       () => props.id ?? `iui-carousel-${getRandomValue(10)}`,
     );
 
-    useTheme();
+    useGlobals();
 
     const isManuallyUpdating = React.useRef(false);
     const carouselRef = React.useRef<HTMLElement>(null);

packages/itwinui-react/src/core/Carousel/CarouselDotsList.tsx

@@ -10,7 +10,7 @@ import {
   getWindow,
   useMergedRefs,
   useResizeObserver,
-  useTheme,
+  useGlobals,
 } from '../utils/index.js';
 import { CarouselDot } from './CarouselDot.js';
 import '@itwin/itwinui-css/css/carousel.css';
@@ -59,7 +59,7 @@ export const CarouselDotsList = React.forwardRef<
     ...rest
   } = props;
 
-  useTheme();
+  useGlobals();
 
   const context = React.useContext(CarouselContext);
   const slideCount =