Breakdown trees: Integrating into tree widget from `@itwin/[email protected]` and above

[grigasp]

This issue lists the problems and, in some cases, solutions to them, for making it possible to integrate Tree components from @itwin/breakdown-trees-react into a tree widget from @itwin/[email protected], with as little effort as possible.

Dependency requirements

The first thing that needs to be done is dependency update. Key points here:

• The components use @itwin/[email protected] APIs and have a peer dependency on it.
• The components are going to be hosted in the context of: iTwin.js v4, React 18, AppUI v5, iTwinUI v3, Tree widget v3. Peer dependencies of the @itwin/breakdown-trees-react packages must satisfy requirements of the context.

Dependencies' update status

Status of updating dependencies to satisfy host's requirements:

• React v17 -> v18. In turn, this required to update these:

  • redux and related packages (we may be able to drop redux altogether),
  • @wojtekmaj/enzyme-adapter-react-17 - it doesn't look like there's an alternative for React 18, needs further investigation if we want the tests to run.

  This also required a few small code changes.

• AppUI v5:

  • useResizeObserver is removed, I replaced it with this.
  • AppUI v5 is ESM-only. This means we can only run our tests in ESM - this requires some mocha configuration adjustments.
  • A lot of deprecated APIs - reacting to them would be a significant effort.

• Tree widget:

  • Since Tree widget v3 got a significant refactor, we can only update @itwin/breakdown-trees-react to use widget v2 - that is straightforward. However, since the host is going to use widget v3, some fiddling with dependencies is needed by the host:

    // in host's .pnpmfile.cjs
    module.exports = {
      hooks: {
        readPackage(pkg, _context) {
          if (pkg.name === "@itwin/breakdown-trees-react") {
            pkg.dependencies["@itwin/tree-widget-react"] = pkg.peerDependencies["@itwin/tree-widget-react"];
            delete pkg.peerDependencies["@itwin/tree-widget-react"];
          }
          return pkg;
        },
      },
    };
    

• iTwin.js v4 - no issues, peer dependency is already on v4.

• iTwinUI v3 - was on v2, but updating didn't result in any visible issues.

Summary

If all we want is to render tree components from @itwin/breakdown-trees-react and we're okay ignoring the tests and lint errors, it's pretty easy.

However, if we're thinking about a proper component, then I suggest we start fresh, and add a new one into tree-widget-react itself. Rewriting this as a simple hierarchy-only (no display control, no actions) component is pretty straightforward, and I personally would feel much safer knowing that it's based on up-to-date dependencies and no hacks are required to integrate it.