react-xarrows - npm Package Compare versions

Comparing version 1.7.2 to 2.0.0

CHANGELOG.md

@@ -0,1 +1,22 @@
+# V2.0
+
+top level `Xwrapper` context and `useXarrow` hook added!
+
+### new features
+- top level API components added: `Xwrapper` wrapper and `useXarrow` hook.
+- `zIndex` prop added to `Xarrow`
+
+### breaking changes
+
+- `label` prop renamed to `labels`
+- **`startAnchor.offset.rightness` renamed to `startAnchor.offset.x`.**
+- **`startAnchor.offset.bottomness` renamed to `startAnchor.offset.y`.**  
+  same for `endAnchor`.
+- **`gridBreak`** type changed from number to string. API changed(see readme)!  
+- **`headShape` and `tailShape`** breaking change: custom svg is now supported using jsx only. 
+  headShape.svgElem is now jsx element and not a string. headShape.svgProps removed!
+  example: `headShape={ svgElem: <path d="M 0 0 L 1 0.5 L 0 1 L 0.25 0.5 z" />, offsetForward: 0.25 }`  
+  same for tailShape.
+  
+
 ## v1.7.2:
@@ -72,3 +93,3 @@ bundler is now webpack, optimized and smaller bundle size.
 - a new powerful feature: `passProps` - now its possible to pass methods (such event handlers) or attributes to the
-  inner components of Xarrow.
+  inner components of Index.
 - `consoleWarning` default prop changed to `false`.
@@ -75,0 +96,0 @@ - bug fixes and inner optimizations(arrow head implemnted now purly using path element without marker elements).## 1.2.0

lib/index.d.ts

@@ -1,3 +0,6 @@
-export { default } from './Xarrow';
+export { default } from './Xarrow/Xarrow';
 export * from './types';
+export * from './constants';
+export { default as Xwrapper } from './Xwrapper';
+export { default as useXarrow } from './useXarrow';
 //# sourceMappingURL=index.d.ts.map

lib/types.d.ts

@@ -1,32 +0,3 @@
-/// <reference types="react" />
-export declare const tAnchorEdge: readonly ["middle", "left", "right", "top", "bottom", "auto"];
-export declare const tPaths: readonly ["smooth", "grid", "straight"];
-export declare const tSvgElems: readonly ["circle", "ellipse", "line", "path", "polygon", "polyline", "rect"];
-export declare const tFacingDir: readonly ["auto", "inwards", "outwards", "left", "right", "up", "down"];
-export declare const arrowShapes: {
-    readonly arrow1: {
-        readonly svgElem: "path";
-        readonly svgProps: {
-            readonly d: "M 0 0 L 1 0.5 L 0 1 L 0.25 0.5 z";
-        };
-        readonly offsetForward: 0.25;
-    };
-    readonly heart: {
-        readonly svgElem: "path";
-        readonly svgProps: {
-            readonly d: "M 0,0.25 A 0.125,0.125 0,0,1 0.5,0.25 A 0.125,0.125 0,0,1 1,0.25 Q 1,0.625 0.5,1 Q 0,0.625 0,0.25 z";
-        };
-        readonly offsetForward: 0.1;
-    };
-    readonly circle: {
-        readonly svgElem: "circle";
-        readonly svgProps: {
-            readonly r: 0.5;
-            readonly cx: 0.5;
-            readonly cy: 0.5;
-        };
-        readonly offsetForward: 0;
-    };
-};
-export declare const tArrowShapes: ("circle" | "arrow1" | "heart")[];
+import React, { ReactSVG } from 'react';
+import { cAnchorEdge, cArrowShapes, cPaths, cSvgElems } from './constants';
 export declare type xarrowPropsType = {
@@ -37,3 +8,3 @@ start: refType;
     endAnchor?: anchorType;
-    label?: labelType | labelsType;
+    labels?: labelType | labelsType;
     color?: string;
@@ -51,3 +22,3 @@ lineColor?: string | null;
     curveness?: number;
-    gridBreak?: number;
+    gridBreak?: string;
     dashness?: boolean | {
@@ -61,2 +32,3 @@ strokeLen?: number;
     animateDrawing?: boolean | number;
+    zIndex?: number;
     passProps?: JSX.IntrinsicElements[svgElemType];
@@ -77,11 +49,11 @@ SVGcanvasProps?: React.SVGAttributes<SVGSVGElement>;
 };
-export declare type pathType = typeof tPaths[number];
+export declare type pathType = typeof cPaths[number];
 export declare type _anchorType = anchorNamedType | anchorCustomPositionType;
 export declare type anchorType = _anchorType | _anchorType[];
-export declare type anchorNamedType = typeof tAnchorEdge[number];
+export declare type anchorNamedType = typeof cAnchorEdge[number];
 export declare type anchorCustomPositionType = {
     position: anchorNamedType;
     offset: {
-        rightness?: number;
-        bottomness?: number;
+        x?: number;
+        y?: number;
     };
@@ -96,25 +68,9 @@ };
 export declare type labelType = JSX.Element | string;
-export declare type svgCustomTypeGeneric<T extends svgElemType> = {
-    svgElem: T;
-    svgProps?: JSX.IntrinsicElements[T];
+export declare type svgCustomEdgeType = {
+    svgElem: JSX.IntrinsicElements[keyof ReactSVG];
     offsetForward?: number;
 };
-export declare type svgCustomEdgeType = {
-    [K in svgElemType]: svgCustomTypeGeneric<K>;
-}[svgElemType];
-export declare type svgEdgeShapeType = typeof tArrowShapes[number];
+export declare type svgEdgeShapeType = typeof cArrowShapes[number];
 export declare type svgEdgeType = svgEdgeShapeType | svgCustomEdgeType;
-export declare type svgElemType = typeof tSvgElems[number];
-export declare type dimensionType = {
-    x: number;
-    y: number;
-    right: number;
-    bottom: number;
-};
-export declare type _prevPosType = {
-    start: dimensionType;
-    end: dimensionType;
-};
-export declare type anchorEdgeType = 'left' | 'right' | 'top' | 'bottom';
-export declare type _xarrowVarPropsType = Omit<xarrowPropsType, 'start' | 'end'>;
+export declare type svgElemType = typeof cSvgElems[number];
 //# sourceMappingURL=types.d.ts.map

package.json

 {
   "name": "react-xarrows",
-  "version": "1.7.2",
+  "version": "2.0.0",
   "author": "Eliav Louski",
@@ -19,3 +19,3 @@ "description": "Draw arrows (or lines) between components in React!",
     "clear:lib": "del /q lib && for /d %x in (lib\\*) do @rd /s /q \"%x\"",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "yarn run build"
   },
@@ -33,2 +33,6 @@ "homepage": "https://eliav2.github.io/react-xarrows/",
   },
+  "funding": {
+    "type": "individual",
+    "url": "https://www.paypal.com/donate?hosted_button_id=CRQ343F9VTRS8"
+  },
   "peerDependencies": {
@@ -59,2 +63,3 @@ "react": ">=16.8.0"
     "jest": "^27.0.5",
+    "react": "^17.0.2",
     "style-loader": "^3.0.0",
@@ -61,0 +66,0 @@ "ts-loader": "^9.2.3",

README.md

@@ -12,12 +12,13 @@ # react-xarrows
 
-#### main features
+### Main features
 
-- Connect between elements by passing a ref or an id for startElement and endElement.
-- Automatic anchoring based on smallest path.
-- Fast algorithm to find path and to adjust canvas.
-- Customization is easy but flexible
+- Connect arrows/lines between components just by passing an id or ref!
+- Super simple API yet fully customizable usage!
+- Smart and Intuitive look and behavior!
+- Smart React lifecycle, and cached parsed props for efficiency!
 
-found a problem? not a problem! post a new issue([here](https://github.com/Eliav2/react-xarrows/issues)).
+liked my work? star [this repo](https://github.com/Eliav2/react-xarrows).
 
-liked my work? please star [this repo](https://github.com/Eliav2/react-xarrows).
+reallyy liked my work? [buy me a coffee](https://www.paypal.com/donate?hosted_button_id=CRQ343F9VTRS8)!  
+this project needs funding to stay open source and free :blush:
 
@@ -50,7 +51,3 @@ ## installation
 
-const boxStyle = {
-    border: "grey solid 2px",
-    borderRadius: "10px",
-    padding: "5px",
-};
+const boxStyle = {border: "grey solid 2px", borderRadius: "10px", padding: "5px"};
 
@@ -61,8 +58,4 @@ function SimpleExample() {
         <div style={{display: "flex", justifyContent: "space-evenly", width: "100%"}}>
-            <div ref={box1Ref} style={boxStyle}>
-                hey
-            </div>
-            <p id="elem2" style={boxStyle}>
-                hey2
-            </p>
+            <div ref={box1Ref} style={boxStyle}>hey</div>
+            <p id="elem2" style={boxStyle}>hey2</p>
             <Xarrow
@@ -79,36 +72,160 @@ start={box1Ref} //can be react ref
 
+### V2 example
+
+in order to invoke updates on xarrows wrap your arrows and connceted elements with `Xwrapper`, and consume `useXarrow`
+on connected elements.
+
+```jsx
+import React from 'react';
+import Xarrow, {useXarrow, Xwrapper} from 'react-xarrows';
+import Draggable from 'react-draggable';
+
+const boxStyle = {border: 'grey solid 2px', borderRadius: '10px', padding: '5px'};
+
+const DraggableBox = ({id}) => {
+    const updateXarrow = useXarrow();
+    return (
+        <Draggable onDrag={updateXarrow} onStop={updateXarrow}>
+            <div id={id} style={boxStyle}>
+                {id}
+            </div>
+        </Draggable>
+    );
+};
+
+export function V2Example() {
+    return (
+        <div style={{display: 'flex', justifyContent: 'space-evenly', width: '100%'}}>
+            <Xwrapper>
+                <DraggableBox id={'elem1'}/>
+                <DraggableBox id={'elem2'}/>
+                <Xarrow start={'elem1'} end="elem2"/>
+            </Xwrapper>
+        </div>
+    );
+}
+```
+
+<details>
+
+<summary markdown='span'>another example</summary>
+
+```tsx
+import React from 'react';
+import Xarrow, {useXarrow, xarrowPropsType, Xwrapper} from 'react-xarrows';
+import Draggable from 'react-draggable';
+
+const boxStyle = {
+    border: '1px #999 solid',
+    borderRadius: '10px',
+    textAlign: 'center',
+    width: '100px',
+    height: '30px',
+    color: 'black',
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'center',
+} as const;
+
+const canvasStyle = {
+    width: '100%',
+    height: '100vh',
+    background: 'white',
+    overflow: 'auto',
+    display: 'flex',
+    color: 'black',
+} as const;
+
+const DraggableBox = ({box}) => {
+    const updateXarrow = useXarrow();
+    return (
+        <Draggable onDrag={updateXarrow} onStop={updateXarrow}>
+            <div id={box.id} style={{...boxStyle, position: 'absolute', left: box.x, top: box.y}}>
+                {box.id}
+            </div>
+        </Draggable>
+    );
+};
+
+const SimpleTemplate = () => {
+    const box = {id: 'box1', x: 20, y: 20};
+    const box2 = {id: 'box2', x: 320, y: 120};
+    const box3 = {id: 'box3', x: 50, y: 150};
+    const box4 = {id: 'box4', x: 320, y: 220};
+    return (
+        <div style={canvasStyle} id="canvas">
+            <Xwrapper>
+                <DraggableBox box={box}/>
+                <DraggableBox box={box2}/>
+                <Xarrow start={'box1'} end={'box2'}/>
+                <Xarrow start={'box1'} end={'box2'} endAnchor={'top'}/>
+                <Xarrow start={'box1'} end={'box2'} startAnchor={'bottom'}/>
+            </Xwrapper>
+            <Xwrapper>
+                <DraggableBox box={box3}/>
+                <DraggableBox box={box4}/>
+                <Xarrow start={'box3'} end={'box4'}/>
+            </Xwrapper>
+        </div>
+    );
+};
+```
+
+(will render this)
+
+<img src="https://user-images.githubusercontent.com/47307889/126083727-1c15f86f-9921-4d9b-933a-5e237d8e1916.png" width="450px"/>
+
+</details>
+
 ## Usage
 
-react-xarrows does not renders automatically if one of the connected elements is rendered. You have to manually trigger
-an update on the arrows whenever one of the connected elements renders(possibaly by trigger update on the parent of the
-arrows) ,this is because the Xarrow component does not have any control or awareness of the connected elements. in
-addition.
-**this is planned to be changed in react-xarrows v2.**
+react-xarrow v2.0 released! no need to trigger render on parents anymore!  
+react-xarrows will smartly trigger updates on relevant elements! use `Xwrapper` and `useXarrow` hook to achieve
+selective rendering!
 
-### Contributing
+##### breaking changes
 
-Want a feature that is not supported? found a bug?\
-no need to clone the repo and set up the dev environment anymore!\
-here's a ready to use development environment with a click of a button(patience, it takes about a minute to setup):
+V2.0 introduced some breaking changes, mainly related to properties naming. see [CHANGELOG.md](./CHANGELOG.md) for
+details.
 
-[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/Eliav2/react-xarrows/blob/master/src/index.tsx)
+#### useXarrow
 
-this will set up environment that will clone react-xarrow master,and will link the code from the src to the examples,
-and will start examples,with typescript watch process that will recompile when any change is made.\
-this means that any code changes in src/Xarrow.tsx will immediately be reflected to the running example at port 3000!
-(add console.log("test") line and see!)\
-to reproduce this dev env on your local machine git clone and follow same commands as in [gitpod.yml](./.gitpod.yml).
+```jsx
+import {useXarrow} from "react-xarrow"
 
-if you made an improvement that is relevant for most users, you can quickly submit a pull request.  
-Please always pull request from and into dev branch -
-here's [Gitpod](https://gitpod.io/#https://github.com/Eliav2/react-xarrows/blob/dev/src/index.tsx)
+const YourComponent = ({id, ...props}) => {
+    const updateXarrow = useXarrow()
+    //...
+    return (
+        <div id={id}>
+            ...
+        </div>
+    )
 
-### react-xarrows v2
+}
+```
 
-v2 is on its way. want to contribute and participate in plannig the next react architecture for react-xarrows? see
-discussion [here](https://github.com/Eliav2/react-xarrows/discussions/53)!
+#### Xwrapper
 
+```jsx
+const YourApp = () => {
+    return (
+        // ...
+        <Xwrapper>
+            <YourComponent id={'comp1'}/>
+            <YourComponent id={'comp2'}/>
+            <Xarrow start={'comp1'} end={'comp2'}/>
+        </Xwrapper>
+        // ...
+    )
+}
+```
+
+each time component calling useXarrow hook renders also the xarrows inside the wrapping Xwrapper wrapper will render.
+receiving `updateXarrow` is optional. use this function only if you want to trigger a render different phase from
+rendering(like click or drag event).
+
 ### API
 
-to see full typescript definition see [types.ts](./src/types.ts) file.
+to see full typescript definition see [types.ts](src/types.ts) file.
 
@@ -123,3 +240,3 @@ here's a summary of the all the available props:
 [endAnchor](#anchors)|at which side the arrow should end at end element| 'auto'|string/object/array
-[label](#label)|optional labels| null|string/array
+[labels](#labels)|optional labels| null|string/array
 [color](#colors)|color of Xarrow(all parts)| 'CornflowerBlue'|string
@@ -134,3 +251,3 @@ [lineColor](#colors)|color of the line| null|string
 [curveness](#curveness)|how much the line curveness when path='smooth'| 0.8|number
-[gridBreak](#gridBreak)|where the line breaks in path='grid'| 0.5|number
+[gridBreak](#gridBreak)|where the line breaks in path='grid'| "50%" | string
 [dashness](#dashness)|should the line be dashed| false|boolean/object
@@ -143,2 +260,3 @@ [showHead](#shows)|show the arrow head?| true|boolean
 [tailShape](#customsvgs)|shape of the arrow tail|'arrow1'|string/object
+zIndex|[zIndex](https://developer.mozilla.org/en-US/docs/Web/CSS/z-index) - Overlapping elements with a larger z-index cover those with a smaller one|0|number
 
@@ -172,7 +290,5 @@ <details>
 
-This API is built in such way that most props can accept different types. you can keep things simple or provide more
-custom props for more custom behavior - the API except both(see [`startAnchor`](#anchors) or `label`
-properties for good examples)
-.<br/>
-see typescript types above for detailed descriptions of what type excepts every prop.
+This API built in such way that most props can accept different types. you can keep things simple or provide more custom
+props for more custom behavior(see [`startAnchor`](#anchors) good example). <br/>
+explore typescript for detailed descriptions of what type excepts every prop.
 
@@ -182,3 +298,3 @@ ## Properties
 This documentation is examples driven.\
-The examples is sorted from the most common use case to the most custom one.
+The examples sorted from the most common use case to the most custom one.
 
@@ -230,2 +346,4 @@ <a name="refs"></a>
 - `endAnchor="middle"` will set the anchor of the end of the line to the middle of the end element.
+- `endAnchor="auto"` choose the closest anchor.
+- `endAnchor="left"` connect to the left.
 
@@ -239,16 +357,14 @@ #### custom usage:
     position: anchorPositionType;
-    offset: { rightness?: number; bottomness?: number };
+    offset: { x?: number; y?: number };
 };
 ```
 
-you can offset the anchor from normal positioning. NOTE: breaking changes in naming in v2.
-
 example:
 
-- `endAnchor= { position: "auto", offset: { rightness: 20 } }` will choose automatic anchoring for end anchor but will
-  offset it 20 pixels to the right after normal positioning.
+- `endAnchor= { position: "auto", offset: { x: 20 } }` will choose automatic anchoring for end anchor but will offset it
+  20 pixels to the right after normal positioning.
 
 if list is provided - the minimal length anchors will be chosen from the list. example:
 
-- `endAnchor= ["right", {position: "left", offset: {bottomness: -10}}]` only right and left anchors will be allowed for
+- `endAnchor= ["right", {position: "left", offset: {y: -10}}]` only right and left anchors will be allowed for
   endAnchor, and if the left side connected then it will be offset 10 pixels up.
@@ -258,14 +374,14 @@
 
-<a name="label"></a>
+<a name="labels"></a>
 
 <details>
 
-<summary markdown='span'> label </summary>
+<summary markdown='span'> labels </summary>
 
 you can place up to 3 labels. see examples
 
-- ```label="middleLabel"``` - middle label
-- ```label=<div style={{ fontSize: "1.3em", fontFamily: "fantasy", fontStyle: "italic" }}>styled middle label</div>``` -
-  custom middle label
-- ```label={{ start:"I'm start label",middle: "middleLabel",end:<div style={{ fontSize: "1.3em", fontFamily: "fantasy", fontStyle: "italic" }}>big end label</div> }}```
+- ```labels="middleLabel"``` - middle label
+- ```labels=<div style={{ fontSize: "1.3em", fontFamily: "fantasy", fontStyle: "italic" }}>styled middle label</div>```
+    - custom middle label
+- ```labels={{ start:"I'm start label",middle: "middleLabel",end:<div style={{ fontSize: "1.3em", fontFamily: "fantasy", fontStyle: "italic" }}>big end label</div> }}```
   start and middle label and custom end label
@@ -340,7 +456,10 @@
 
-defines where the line will break when `path='grid'`. value should be a number from 0 to 1.
+defines where the line will break when `path='grid'`.
 
 examples:
 
-- `gridBreak={0.2}` the line would break closer to start element(20% of the path instead of 50%).
+- `gridBreak='20%'` the line would break closer to start element(20% of the path instead of 50%).
+- `gridBreak='50'` the line would break 50 pixel from start element.
+- `gridBreak='20%50'` the line would break 50 pixel after 20% from start element.
+- `gridBreak='100%-50'` the line would break 50 pixel before end element.
 
@@ -401,8 +520,5 @@ </details>
 
+you can customize the svg edges (head or tail) of the arrow. you can use predefined svg by passing string,one
+of `"arrow1" | "circle" | "heart"`
 
-[//]: # (todo: add svg custom shapes docs!)
-
-new feature! you can customize the svg edges (head or tail) of the arrow. you can use predefined svg by passing
-string,one of `"arrow1" | "circle" | "heart"`
-
 #### simple usage:
@@ -471,11 +587,8 @@
 
-```typescript
-headShapeType = {
-    svgElem: T
-:
-'circle' | 'ellipse' | 'line' | 'path' | 'polygon' | 'polyline' | 'rect';
-svgProps ? : JSX.IntrinsicElements[T];
-offsetForward ? : number;
-}
-;
+```ts
+type svgElemType = "circle" | "ellipse" | "line" | "path" | "polygon" | "polyline" | "rect"
+type headShapeType<T extends svgElemType> = {
+    svgElem: SVGElementTagNameMap[T];
+    offsetForward?: number;
+};
 ```
@@ -485,12 +598,9 @@
 
-```js
-headShape = {
-    svgElem: 'path',
-    svgProps: {d: `M 0 0 L 1 0.5 L 0 1 L 0.25 0.5 z`},
-    offsetForward: 0.25
-}
+```tsx
+const headShapeArrow1 = {svgElem: <path d="M 0 0 L 1 0.5 L 0 1 L 0.25 0.5 z"/>, offsetForward: 0.25}
+// then pass it Xarrow
+<Xarrow headShape={headShapeArrow1}/>
 ```
 
-`svgElem` - an svg element like `path` or `circle`.  
-`svgProps` - props that will be passed to the svg element.
+`svgElem` - a jsx of svg element like `path` or `circle`(can also imported svg element from file).  
 `offsetForward` - how much to offset tht line into the svg element(from 0 to 1). normally the line will connect to the
@@ -502,4 +612,3 @@ start of the svgElem. for example in case of the default arrow you want the line to enter 25% into the svgElem.
 **in case you pass a custom svg element:** currently you have to adjust the path to start from 0,0 and to be at size box
-1x1 in order to make the custom shape look like the default shapes in size, in later versions it is planned to support
-automatic adjustment using getBBox() function.
+1x1 in order to make the custom shape look like the default shapes in size.
 
@@ -561,4 +670,2 @@ </details>
 
-[//]: # (todo: check if width and height can't be automatically determined)
-
 ##### _extendSVGcanvas
@@ -579,3 +686,6 @@
 
-If you/your company are using this project, and you want to contribute to his development, please consider donating.  
+It takes many hours to develop and maintain this library, and it is not funded by any company or commercial
+organization.
+
+If you/your company are using this project, please consider donating.  
 Any donation will help me to devote more time to the development of this project.
@@ -585,3 +695,20 @@
 
+### Contributing
 
+Want a feature that is not supported? found a bug?\
+no need to clone the repo and set up the dev environment anymore!\
+here's a ready to use development environment with a click of a button(patience, it takes about a minute to setup):
+
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/Eliav2/react-xarrows/blob/master/src/index.tsx)
+
+this will set up environment that will clone react-xarrow master,and will link the code from the src to the examples,
+and will start examples,with typescript watch process that will recompile when any change is made.\
+this means that any code changes in src/* will immediately be reflected to the running example at port 3000!
+(add console.log("test") line and see!)\
+to reproduce this dev env on your local machine git clone and follow same commands as in [gitpod.yml](./.gitpod.yml).
+
+if you made an improvement that is relevant for most users, you can quickly submit a pull request.  
+Please always pull request from and into dev branch -
+here's [Gitpod](https://gitpod.io/#https://github.com/Eliav2/react-xarrows/blob/dev/src/index.tsx)
+
 ## Versions
@@ -588,0 +715,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

121129

increased by23.62%

Number of package files

29

increased by93.33%

Lines of code

1849

increased by31.41%

Number of lines in readme file

707

increased by21.9%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Dev dependency count

30

increased by3.45%

No dependency changes