Skip to content

Instantly share code, notes, and snippets.

@ChrisShank

ChrisShank/README.md

Last active May 1, 2024 23:54
Show Gist options
  • Save ChrisShank/4520d4e30c6461415973dee7989bd516 to your computer and use it in GitHub Desktop.
Save ChrisShank/4520d4e30c6461415973dee7989bd516 to your computer and use it in GitHub Desktop.
Download ZIP
Perfect Arrow starterkit
Raw
README.md

Perfect Arrow

A custom element to declaratively define arrows between HTML elements. Steve Ruiz's perfect-arrows powers to arrow layout and Sam Thor's viz-observer to observer the movement and resizing of elements.

Warning

This library is still in development. 🚧 Use at your own risk. It's published to npm, but expect breaking changes until we flesh things out.

Usage

  1. Install the NPM package perfect-arrow using a package manager of your choice.

  2. Register the custom element and start using it in HTML

<div id="box1"></div>
<div id="box2"></div>
<perfect-arrow type="box" source="box1" target="box2"></perfect-arrow>

<script type="module">
  import { PerfectArrow } from 'perfect-arrow';
  // Register the `<perfect-arrow>` custom element.
  PerfectArrow.register();
</script>

API

Required attributes/properties

  • source: (String) An id for the element that is the source of the arrow.
  • target: (String) A id for the element that is the target of the arrow.

Optional attributes/properties

  • type: (String) The type of layout algorithm to use. 'box' will render the arrow around the border-box of each element. 'point' will render the arrow on the midpoint of each element. tab=readme-ov-file#getboxtoboxarrowx0-y0-w0-h0-x1-y1-w1-h1-options) and getArrow, respectively.
  • bow: (Number) A value representing the natural bow of the arrow. At 0, all lines will be straight.
  • stretch: (Number) The effect that the arrow's length will have, relative to its minStretch and maxStretch, on the bow of the arrow. At 0, the stretch will have no effect.
  • stretch-min: (Number) The length of the arrow where the line should be most stretched. Shorter distances than this will have no additional effect on the bow of the arrow.
  • stretch-max: (Number) The length of the arrow at which the stretch should have no effect.
  • pad-start: (Number) How far the arrow's starting point should be from the provided start point.
  • pad-end: (Number) How far the arrow's ending point should be from the provided end point.
  • flip: (Boolean) Whether to reflect the arrow's bow angle.
  • straights: (Boolean) Whether to use straight lines at 45 degree angles.

Default values

Here are the default values of optional attributes

<perfect-arrow
  type="box"
  bow="0"
  stretch=".25"
  stretch-min="50"
  stretch-max="420"
  pad-start="0"
  pad-end="20"
  straights
></perfect-arrow>

Check out this demo to play around with the different settings.

Extensibility

The custom element is easily extensible via class inheritance. You can update the name of the custom element, add new properties/attributes, override the render method, and add new arrow algorithms.

import { PerfectArrow } from 'perfect-arrow';
import { property } from '@lit/reactive-element/decorators.js';

class MyArrow extends PerfectArrow {
  // Override the name of the custom element
  static tagName = 'my-arrow';

  // Add your own properties/attributes. For example, a weighted edge.
  @property({ type: Number, reflect: true }) weight: number = 0;

  // Render an arrow with your own styles!
  render([sx, sy, cx, cy, ex, ey, ae]: Arrow) {
    // ...
  }
}

MyArrow.register();
Raw
index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Perfect Arrow - Dragging</title>
<style>
html {
height: 100%;
}
body {
min-height: 100%;
position: relative;
margin: 0;
}
draggable-box {
display: block;
width: 50px;
height: 50px;
border: 2px solid black;
position: absolute;
}
perfect-arrow {
display: block;
position: absolute;
top: 0;
right: 0;
bottom: 0;
left: 0;
pointer-events: none;
z-index: -1;
}
</style>
</head>
<body>
<draggable-box id="box1" style="left: 0; top: 0"></draggable-box>
<draggable-box id="box2" style="left: 100px; top: 200px"></draggable-box>
<draggable-box id="box3" style="left: 200px; top: 100px"></draggable-box>
<perfect-arrow source="box1" target="box2"></perfect-arrow>
<script type="module">
import { PerfectArrow } from 'https://esm.sh/[email protected]';
class DraggableBox extends HTMLElement {
static tagName = 'draggable-box';
static register() {
customElements.define(this.tagName, this);
}
constructor() {
super();
this.onMouseDrag = this.onMouseDrag.bind(this);
this.addEventListener('mousedown', () => {
window.addEventListener('mousemove', this.onMouseDrag);
});
window.addEventListener('mouseup', () => {
window.removeEventListener('mousemove', this.onMouseDrag);
});
}
onMouseDrag({ movementX, movementY }) {
const { left, top } = window.getComputedStyle(this);
let leftValue = parseInt(left);
let topValue = parseInt(top);
this.style.left = `${leftValue + movementX}px`;
this.style.top = `${topValue + movementY}px`;
}
}
DraggableBox.register();
PerfectArrow.register();
</script>
</body>
</html>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment