react-xarrows v3 on it's way

[Eliav2]

update 28.12.2022

react-xarrows v3 is now in an early alpha stage (but most of the logic has been implemented). a first alpha release would be released with a docs site(the docs are being worked on).

react-xarrows v2 implemented a huge single component(with some smaller utility components), and each feature was controlled by a set of properties that were passed to this component. this approach does not scale well as complexity grows.

react-xarrows v3 takes a different approach, and emphasizes component composition rather then passing props. in simple words, V3 would give you the tools to compose your own custom arrow using composition, hooks, and utilities that abstract most of the complicated logic rather than trying to implement every possible use case in a single component and adjust it using props.

react-xarrows v3 chooses flexibility over simplicity. while v2 chose simplicity.

The new API emphasizes component composition, similar to MUI, and will remind it to some extent.

V3 is definitely considered a breaking change as the API changed significantly.

old post

react-xarrows v3 is on its way.
the main purpose of this new major version is to separate logic about different features to different extendible components. the change is mostly internal but the behavior of the react-arrows might change as the entire lib structure has changed and things working quite differently now. this is why it is considered a new major version.

on V3, any developer could simply use the default exported Xarrow component, or construct and extend its own Xarrow component using the different separate internal components. this would help me and possible future contributors to enhance this lib over time, yet keeping it simple to use and performant.

Interesting! explain me farther about the new internal!

in v3 the internal components are built using the render props pattern, and each component is responsible for a single feature of react-xarrows.

without going too much into details, an example for custom xarrow could like this:
for example XarrowCore (the first element in the tree) would be responsible for managing state, XarrowBasicPath for passing down possible(and extensible) path, XarrowAnchors would be responsible for choosing the best anchor based on the current state, and so on.

export interface CustomXarrowProps extends XarrowCoreAPIProps, XarrowBasicAPIProps, XarrowAnchorsAPIProps {}

const CustomXarrow: React.FC<CustomXarrowProps> = (props) => {
  const { start, end, SVGcanvasProps, SVGcanvasStyle, divContainerProps, ...rest } = props;
  return (
    <XarrowCore {...{ start, end, SVGcanvasProps, SVGcanvasStyle, divContainerProps }} {...rest}>
      {(elems) => {
        return (
          <XarrowBasicPath {...elems}>
            {(getPath) => {
              let { startElem, endElem } = elems;
              return <XarrowAnchors {...{ startElem, endElem, getPath }} {...rest} />;
            }}
          </XarrowBasicPath>
        );
      }}
    </XarrowCore>
  );
};

we can see XarrowCore receives start and end props (and some extra props for the SVG or the div elements).
then XarrowCore passes to his children component the state of these elements, so the component could potentially do anything with it.
next, this state is passed to XarrowBasicPath which returns an extensible getPath to his children. this state is used by XarrowAnchors which changes this state to choose the best anchor based on the positions of the elements. and so on.

Update! new-new architecture

An even simpler approach has been decided:

a special class that receives xarrowFeature object classes and returns a new React Component constructed of their features.

const features = [Core, Anchors, Path];

const XarrowCustom = XarrowBuilder(features);

each feature object is constructed of properties that are functions for example changing state and for rendering jsx, state change function execute first and only after jsx functions:

const Core: XarrowFeature<CoreProps> = {
  propTypes: {
    // ...
  },
  state: (state, props) => {
    // hooks, state changes here...
   return {newState}
  },
  jsx: (prevJsx, state, props) => {
    //jsx preprocessing here...

    return (
      // some jsx returned
      <div>
        <svg>
          <path d={state.getPath(state.posSt)} />
          {/* your jsx Xarrow jsx  implementation here */}
        </svg>
      </div>
    );
  },
};

this architecture would allow developers to write a custom plugins for this lib.

some of the planned changes are:

• new internal structure that made customization of Xarrow much easier.
• much efficient and smart lifecycle.
• delay each render of Xarrow (using memorization- no performance cost) so xarrow could sample the lastest DOM frame, even after other react components which Xarrow may depend on them. see updateXarrow on a grid #89.
• when one of the connected elements does not appear, draw to the lastest remembered position Avoid to render arrow when property "START" or "END" doesn't exist. #86
• allowing offsetting anchors relative to the currently chosen anchor. offset anchors towards facing direction  #92
• much more.
• new Xelem component to pass updateXarrow directly to children components.
  currently, in order to invoke updates on xarrow you have to consume useXarrow hook on components that use Xarrow. however, sometimes they appear on the current component tree and you don't want to extract them to a different component, or worse, you can't because you prefer class components.

most of the changes are about better developer experience, better API, better performance, and better internal structure. not about new features.

no breaking changes are currently planned, but this may change as work is going on.

stay tuned!

[bismareeo]

Awesome @Eliav2. I am excited about the new version!

[bonellia]

Also looking forward to newer version. Thanks for your valuable work!

[joealden]

@Eliav2 any update on the status of this? Just interested to see if any progress has been made!

[bismareeo]

@Eliav2 any update on the react-arrows v3?

[Andonvr]

Just discovered this project, loving it! Really easy to use.

Any update on v3?

[farukbigez]

It seems this project stopped working on it. Still, minimalist and has a good potential, tho.

[Andonvr]

I found an alternative, react-archer was good enough for me.

[farukbigez]

it's a good component but not easy to use. This package was easy to use.

[joealden]

@Eliav2 any update?

[anserwaseem]

@Eliav2 ìs there anyone working on it?

[farukbigez]

Everyone, migrated to react-archer

[Eliav2]

an alpha version of react-xarrows v3 will be released soon. and docs site as well.

[Nathan-Priebe]

Any update on this?