Skip to content

v5.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 16 Dec 11:44
release/5.0.0
4300aad

5.0.0 Change Notes

Table of contents:

Drop support for iTwin.js 3.x

iTwin.js 3.x is in the end-of-life phase as described in the version support policy.

iTwin.js peer dependency ranges have been updated to exclude version ^3.7.0. #1050

Application consumers of AppUI should upgrade to the latest iTwin.js 4.x version. Packages that depend on AppUI should update to the minimum required iTwin.js 4.x version.

Support for newer versions of iTwin.js will be added in future AppUI releases.

Drop support for React 17.x

React peer dependency ranges have been updated to exclude version ^17.0.0. #1054

Application consumers of AppUI should upgrade to the latest React 18.x version. Packages that depend on AppUI should update to the minimum required React 18.x version.

Support for newer versions of React will be added in future AppUI releases.

Drop support for iTwinUI 2.x

iTwinUI 2.x is in the end-of-life phase as described in the version support policy.

AppUI packages will no longer support the iTwinUI 2.x version out of the box. Previously, AppUI would install both iTwinUI 2.x and iTwinUI 3.x to set up both versions when using the ThemeManager or popout windows. #1058

Application consumers of AppUI should upgrade to the latest iTwinUI 3.x version. Packages that depend on AppUI should update to the minimum required iTwinUI 3.x version.

Applications that want to continue using iTwinUI 2.x in AppUI must be wrapped with the ThemeProvider from iTwinUI 2.x.
Additionally, to use iTwinUI 2.x in child windows and popout widgets, applications can use the newly introduced childWindow prop to wrap the content of child windows. For example:

import { ThemeProvider } from "@itwin/itwinui-react-v2";

function ChildWindow(props: React.PropsWithChildren<{}>) {
  // Wrap content of child windows with `ThemeProvider` from iTwinUI 2.x
  return <ThemeProvider>{props.children}</ThemeProvider>;
}

function App() {
  return <ConfigurableUiContent childWindow={ChildWindow} />;
}

Support for newer versions of iTwinUI will be added in future AppUI releases.

Restrict access to @internal APIs

AppUI packages now correctly define an exports field in their package.json files to prevent consumers from importing the @internal APIs directly from submodules. #1048

This change might break consumers that rely on importing APIs directly from unsupported submodules. Currently supported export paths:

  • Main barrel file, i.e. @itwin/appui-react
  • package.json subpath, i.e. @itwin/appui-react/package.json
  • All SCSS files, i.e. @itwin/core-react/lib/core-react/_typography.scss. SCSS exports are available to facilitate the AppUI 5.0 adoption and will be removed in the next major version.

To fix the import issue, consumers should update their import paths to use the supported export paths. For example:

// Before
import { Widget } from "@itwin/appui-react/lib/esm/appui-react/widgets/Widget";

// After
import { Widget } from "@itwin/appui-react";

SCSS imports and variables should be replaced with iTwinUI CSS variables:

// Before
@import "~@itwin/core-react/lib/cjs/core-react/style/themecolors";

.component {
  background-color: $buic-background-1;
}

// After
.component {
  background-color: var(--iui-color-background);
}

Additionally, all @internal API exports are removed from the barrel file, as consumers should never use @internal APIs directly. #1060

Caution

There are still a number of @internal APIs that are exported with their related public types, such as class methods, fields, or namespace functions. These should never be used directly and are subject to change without notice.

If the currently used API is not exported from the barrel file and there is no reasonable replacement, please file an issue and describe your use case.

Drop CommonJS modules

Support for CommonJS modules has been removed from all AppUI packages. #1081

To facilitate the migration, the exports field has been updated to support legacy cjs and esm import paths in SCSS files. For example, @import "@itwin/core-react/lib/cjs/core-react/base/base.scss" will continue to work correctly by resolving to @import "@itwin/core-react/lib/core-react/base/base.scss". Additionally, SCSS files are still delivered in cjs and esm directories to support a wider range of bundlers #1125.
However, consumers should avoid importing SCSS partial files, as these are deprecated and will be removed in the next major version.

Additionally, file extensions are provided in import declarations, which are mandatory for ES modules. #1056

Style sheet changes

SCSS files have been updated to use the @use rule instead of the deprecated @import rule. #1085

To avoid breaking existing SCSS of AppUI consumers, @forward rules were added to SCSS partial files to forward previously imported SCSS modules.

Additionally, all internal usage of --buic CSS variables and $buic SCSS variables have been replaced with iTwinUI CSS variables. #1079

Consumers of AppUI are expected to avoid using AppUI SCSS partial files directly and instead use the available CSS variables from iTwinUI.

Move iTwinUI to peerDependencies

AppUI packages now specify @itwin/itwinui-react as a peer dependency. This change means that application consumers should explicitly specify the latest version of iTwinUI in their package.json dependencies. This change simplifies the process of ensuring that a single version of the iTwinUI package is installed per major version without using version overrides. #1115

@itwin/appui-react

Removals

  • Removed the FrameworkChildWindows.useCreateRoot method, which existed solely to prevent runtime warnings when using React 18.x. Consumers should remove usages of useCreateRoot when upgrading. #1054
  • Removed the activateDroppedTab preview feature, as the behavior of the preview feature is now enabled by default. Additionally, a widget tab's drag-and-drop logic is updated to activate the dropped tab only if it was active when the drag interaction was initiated. It is safe for consumers to remove the preview feature from their PreviewFeaturesProvider. #1071
  • Removed the newToolbars preview feature, as the behavior of the preview feature is now enabled by default. It is safe for consumers to remove the preview feature from their PreviewFeaturesProvider. #1072

Additions

  • Added the childWindow prop to the ConfigurableUiContent component, allowing consumers to provide a wrapper component for child windows and popout widgets. #1058

  • The StatusBarPopover component now accepts all props that are accepted by the Popover component from @itwin/itwinui-react. #1068

  • Add backButton property to ModalFrontstageInfo interface to allow specifying of a custom back button for a modal frontstage. Additionally ModalFrontstageButton component is added to maintain visual consistency between modal frontstages. #1156

    UiFramework.frontstages.openModalFrontstage({
  ...info,
  backButton: (
    <ModalFrontstageButton
      onClick={() => {
        const result = window.confirm("Are you sure you want to go back?");
        if (!result) return;
        UiFramework.frontstages.closeModalFrontstage();
      }}
    />
  ),
});

Changes

  • Popout widgets are now displayed in a flow layout to match the layout of floating, stage panel, and popout widgets when reparentPopoutWidgets is enabled. #1049
  • Use React portal instead of creating a separate element tree for each child window. #1062
  • Removed incorrect usage of the internal IModelApp.renderSystem.options.displaySolarShadows check from useSolarDataProvider. The wantShadows property of the viewport display style is used instead. #1066
  • Removed several references to @bentley/icons-generic by either reusing similar icons from @itwin/itwinui-icons or inlining the icons directly. #1074
  • Add error boundary to popout widgets. #1075
  • Updated the styling of the BackstageAppButton and NestedFrontstageAppButton components to match the updated toolbars. #1078
  • The new toolbars will now handle snap opacity mode when it is enabled. #1082
  • Bump FrameworkFrontstages.addFrontstage method to @public. #1134
  • Add defaultState getter that returns the default state configuration of the widget to WidgetDef class. #1141
  • Specified additional version ranges in redux related peer dependencies. redux version is updated from ^4.1.0 to ^4.1.0 || ^5.0.0 and react-redux version is updated from ^7.2.2 to ^7.2.2 || ^8.0.0 || ^9.0.0. This enables consumers to utilize latest redux capabilities. See redux release v5.0.0 for migration tips. #1151

@itwin/components-react

Deprecations

  • Deprecated the FavoritePropertiesRenderer.renderFavorites method in favor of an overload that doesn't take the createRoot function as an argument. #1054

Additions

  • Added the IMergingPropertyDataProvider interface, which combines any number of IPropertyDataProvider instances, and added the createMergedPropertyDataProvider factory function that creates an IMergingPropertyDataProvider instance. #1040
  • Added a callback to VirtualizedPropertyGrid which determines which editors should always be visible. #1090

Changes

  • Removed a dependency to @bentley/icons-generic by reusing icons from @itwin/itwinui-icons. #1074

@itwin/core-react

Changes

  • Removed the resize-observer-polyfill dependency because ResizeObserver is well supported by modern browsers, eliminating the need for a polyfill. #1045

@itwin/imodel-components-react

Additions

  • Added ToolUtilities namespace that contains utilities for working with iTwin.js core Tool class. #1150

    • ToolUtilities.defineIcon function allows defining an icon for a tool type using a React element. This is a supplement for an existing Tool.iconSpec property that adds additional iconElement property to the tool type.

      // Before
export class MyTool extends Tool {
  public static iconSpec = "icon-placeholder";
}

// After
class MyCoreTool extends Tool {
  public static iconSpec = "icon-placeholder";
}
export const MyTool = ToolUtilities.defineIcon(
  MyCoreTool,
  <SvgPlaceholder />
);

      Alternatively, consumers can simply add an iconElement property of ReactElement type to the tool class.

      export class MyTool extends Tool {
  public static iconSpec = "icon-placeholder";
  public static iconElement = (<SvgPlaceholder />);
}

      Newly defined iconElement property needs to be read by the consumers to display the icon in a toolbar, unless the ToolbarItemUtilities.createForTool helper is used when creating toolbar items.

    • ToolUtilities.isWithIcon function is a type guard that checks if a tool has a React icon element defined. Which is useful to read the icon element from the tool type.

      if (ToolUtilities.isWithIcon(MyTool)) {
  MyTool.iconElement; // ReactElement
}
Assets 2
Loading