@bentley/imodel-react-hooks v0.1.4

iModel.js React Hooks

Description

React hooks for low-overhead and idiomatic imodeljs usage in React where appropriate.

Currently, the useMarker, and useFeatureOverrides hooks.

When and when not to use hooks

React's hooks are fun, and often great, but they require you to deal with state in a scope that will be thrown away, to which references would be mostly memory leaks and bugs. Because of this, you need to stabilize your functions (useCallback), keep track of dependencies manually, etc. And because of this, you cannot define a class with access to React state easily (in a functional component). Although this package did at one point have a hook for using a class directly in a functional component, managing references to outer state requires patterns that thrash prototype chain access caches in modern JS engines and are pretty much a bad idea. So it must be said:

if you are using a class that needs access to state in React, prefer a class component.

Michael Belousov wrote an article on the iModel.js community blog going further in depth than that.

The hooks in this package are either for simple use cases with boilerplate reduction (useMarker), or places where you aren't dealing directly with a dedicated class instance (useFeatureOverrides). Otherwise, try this pattern for integrating any class into your React state:

import React, { useContext } from "react";
import { UserContext, UserContextType } from "./MyApplicationsContexts";
import { PrimitiveTool, BeButtonEvent } from "@bentley/imodeljs-frontend";

const ToolProvider = () => {
  const userContext = useContext(UserContext);
  return <InnerToolProvider userContext={userContext} />;
};

class InnerToolProvider extends React.Component<{
  userContext: UserContextType;
}> {
  MyTool = (() => {
    const componentThis = this;
    return class MyTool extends PrimitiveTool {
      static toolId = "myTool";

      onDataButtonDown(ev: BeButtonEvent) {
        const user = componentThis.props.userContext.name;
        console.log(`${user} pressed here: ${ev.point}`);
        return Promise.resolve(EventHandled.Yes);
      }
    };
  })();

  componentWillMount() {
    IModelApp.tools.register(this.MyTool);
  }
  componentWillUnmount() {
    IModelApp.tools.unRegister(this.MyTool.toolId);
  }
  render() {
    return null;
  }
}

The above works with inheritance, be it in or out of react state, abstract classes, etc. Tools, heavy-duty markers, and other iModel.js subclass-style APIs should prefer this technique.

useMarker

import React from "react";
import { IModelJsViewProvider, useMarker } from "@bentley/imodel-react-hooks";
import mySvgUrl from "my.svg";
import { Point2d } from "@bentley/geometry-core";

const MyPin = (props) => {
  const [clicked, setClicked] = React.useState(false);

  useMarker({
    worldLocation: props.position,
    image: mySvgUrl,
    isHilited: clicked,
    imageSize: Point2d.create(10, 10),
    size: Point2d.create(10, 10),
    onMouseButton: () => {
      setClicked((prev) => !prev);
      return true;
    },
  });

  return <span>{props.name}</span>;
};

const MyApp = (props) => {
  const [pins, setPins] = React.useState([]);

  React.useEffect(() => {
    fetchPins().then((resp) => setPins(resp.data));
  }, []);

  return (
    <IModelJsViewProvider>
      <YourConfiguredIModelJsView />
      <Sidebar>
        {pins.map((pinProps) => (
          <MyPin {...pinProps} />
        ))}
      </Sidebar>
    </IModelJsViewProvider>
  );
};

IModelJsViewProvider allows descendent components to use the useMarker hook, which draws a marker with the given options, which follow the imodeljs Marker API with minor tweaks. View invalidation is handled for you efficiently; you can pass promises to images, and the view will be invalidated for you after it resolved. You can also pass JSX expressions to useMarker's jsxElement option and it will be rendered by react and update correctly.

See examples in the Recipes folder.

IModelJsViewProvider

useMarker(options: UseMarkerOptions): void

The options come from the fields of the @bentley/imodeljs-frontend's Marker class, see its documentation.

There are however, a few deviations:

How it works

The IModelJsViewProvider connects to the IModelApp singleton and allows the hooks to manipulate decorator state in react which is then reflected into the imodel viewport.

useFeatureOverrides

import React, { useState } from "react";
import {
  FeatureOverrideReactProvider,
  useFeatureOverrides,
} from "@bentley/imodel-react-hooks";
import { FeatureSymbology } from "@bentley/imodeljs-frontend";
import { RgbColor } from "@bentley/imodeljs-common";
import { myAppState, C } from "./appState";

const A = () => {
  useFeatureOverrides(
    {
      overrider: (overrides, viewport) => {
        overrides.overrideModel(
          myAppState.imodelconn.id,
          FeatureSymbology.Appearance.fromJSON({
            rgb: new RgbColor(250, 0, 0),
            transparent: 0.5,
          }),
          true
        );
      },
    },
    []
  );
  return null;
};

const B = () => {
  const [isHovered, setIsHovered] = useState(false);
  useFeatureOverrides(
    {
      overrider: (overrides, viewport) => {
        if (isHovered)
          overrides.overrideElement(
            myAppState.selectedElementId,
            FeatureSymbology.Appearance.fromJSON({
              rgb: new RgbColor(0, 0, 250),
              transparency: 0,
            }),
            true
          );
      },
    },
    [isHovered]
  );
  return (
    <div
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
      style={{ height: "40px", width: "40px" }}
    />
  );
};

const MyApp = (props) => (
  <FeatureOverrideReactProvider>
    <A>
      <B />
      <C />
    </A>
  </FeatureOverrideReactProvider>
);

FeatureOverrideReactProvider allows descendent components to set cascading feature overrides in viewports, and the overrides are executed in tree order of the components, so in the above example, overrides from C override B, which overrides A. The overrider property of UseFeatureOverrides is an analog for FeatureOverrideProvider.addFeatureOverrides which you would implement when adding your own vanilla JavaScript IModelJS FeatureOverrideProvider. This hook is useful for when you want multiple components to be able to control one FeatureOverrideProvider in cooperation, or when you don't want to manage notifying the viewport to refresh overrides yourself when you can do it on react state changes.

There are no recipes for this hook yet, but there is room for one to be contributed.

useFeatureOverrides(options: UseFeatureOverridesOpts, deps: any[]): void

FeatureOverrideReactProvider