@bentley/imodel-react-hooks
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.3 • Public • Published

    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

    Property Type Description Default
    viewFilter ((vp: Viewport) => boolean) | undefined Filter which vps marker decorations are allowed to be drawn in. Draw markers in all vps that can be invalidated

    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:

    Name in Marker Type in Marker Name in useMarker Type in useMarker Note
    _scaleFactor Range1dProps scaleFactor Range1dProps | undefined _scaleFactor as an option, so you can set it without subclassing (since it's protected)
    _isHilited boolean isHilited boolean | undefined _isHilited as an option, so you can set it without subclassing (since it's protected)
    _hiliteColor ColorDef hiliteColor ColorDef | undefined _hiliteColor as an option, so you can set it without subclassing (since it's protected)
    image boolean image string | MarkerImage | Promise<MarkerImage> replacement for Marker.setImage and Marker.setImageUrl, accepts urls, loaded images, and promises to images and invalidates the view when the promise resolves
    N/A N/A jsxElement React.ReactElement | undefined like htmlElement, but the JSX Element will create the htmlElement for you (used to override the htmlElement)
    size Point2d size Point2d | {x: number, y: number} | [number, number] for simpler code, useMarker can convert json point representations (arrays or objects containing an x and y prop) for you.
    imageSize Point2d imageSize Point2d | {x: number, y: number} | [number, number] for simpler code, useMarker can convert json point representations (arrays or objects containing an x and y prop) for you.
    imageOffset Point2d imageOffset Point2d | {x: number, y: number} | [number, number] for simpler code, useMarker can convert json point representations (arrays or objects containing an x and y prop) for you.

    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

    Option Type Note
    overrider (overrides: FeatureSymbology.Overrides, viewport: Viewport) => void the code to run in the FeatureOverrideProvider.addFeatureOverrides function for this component
    completeOverride boolean | undefined whether to skip previous components in the component tree and go straight to this one, useful for performance savings when you're overriding everything and allowing earlier components to add overrides would be redundant.

    FeatureOverrideReactProvider

    Property Type Description Default
    viewFilter ((viewport: Viewport) => boolean) | undefined A predicate function which filters which viewports to apply the overrides in apply overrides in every viewport

    Install

    npm i @bentley/imodel-react-hooks

    DownloadsWeekly Downloads

    3

    Version

    0.1.3

    License

    MIT

    Unpacked Size

    122 kB

    Total Files

    49

    Last publish

    Collaborators

    • cshafer
    • philip-mcgraw
    • colinkerr
    • imodeljs