Arrows.svelte component

<!--
  @component
  Adds SVG swoopy arrows based on a config object. It attaches arrows to divs, which are created by another component such as [Annotations.html.svelte](https://layercake.graphics/components/Annotations.html.svelte).
 -->
<script>
  import { tick } from 'svelte';
  import { getLayerCakeContext } from 'layercake';
  import { swoopyArrow, getElPosition, parseCssValue } from '../_modules/arrowUtils.js';

  const k = getLayerCakeContext();

  /**
   * Where an arrow starts, on the annotation's text box.
   * @typedef {Object} ArrowSource
   * @property {string} anchor - A spot on the box as `horizontal-vertical`, e.g. `'right-middle'`. Horizontal is `left`, `middle` or `right`. Vertical is `top`, `middle` or `bottom`.
   * @property {number|string} [dx] - Horizontal nudge, in pixels or as a percentage of the box width.
   * @property {number|string} [dy] - Vertical nudge, in pixels or as a percentage of the box height.
   */

  /**
   * Where an arrow ends. Either a percentage of the chart, like `'68%'`, or a
   * data value that goes through the x and y scales. Leave `x` or `y` out to
   * read it from the annotation with the chart's x or y accessor instead.
   * @typedef {Object} ArrowTarget
   * @property {string|number} [x] - The x position.
   * @property {string|number} [y] - The y position.
   * @property {number|string} [dx] - Horizontal nudge, in pixels or as a percentage of the chart width.
   * @property {number|string} [dy] - Vertical nudge, in pixels or as a percentage of the chart height.
   */

  /**
   * @typedef {Object} Arrow
   * @property {boolean} [clockwise=true] - Which way the arrow bows.
   * @property {ArrowSource} source - Where the arrow starts.
   * @property {ArrowTarget} target - Where the arrow ends.
   */

  /**
   * One annotation, the same object that Annotations.html.svelte or
   * AnnotationsData.html.svelte draws the text for. Only `arrows` matters here.
   * @typedef {Object} Annotation
   * @property {string} text - The annotation's text.
   * @property {Array<Arrow>} [arrows] - The arrows to draw from this annotation.
   */

  /**
   * @typedef {Object} Props
   * @property {Array<Annotation>} annotations - The annotations, in the same order the text component rendered them. See the [Column example](https://layercake.graphics/example/Column) for a full config.
   * @property {string} [containerClass='.chart-container'] - The CSS selector of the element wrapping the `<LayerCake>` component. The arrows crawl it for the annotation divs.
   * @property {string} [annotationClass='.layercake-annotation'] - The CSS selector of the annotation divs.
   */

  /** @type {Props} */
  let {
    annotations,
    containerClass = '.chart-container',
    annotationClass = '.layercake-annotation'
  } = $props();

  /** @type {SVGGElement|undefined} */
  let container = $state();

  // The x side of an arrow works in `left` and `width`, the y side in `top` and `height`
  /** @type {Array<{ dimension: 'width'|'height', css: 'left'|'top', position: 'x'|'y' }>} */
  const lookups = [
    { dimension: 'width', css: 'left', position: 'x' },
    { dimension: 'height', css: 'top', position: 'y' }
  ];

  /** @type {Array<Element>} */
  let annotationEls = $state([]);

  // Find the annotation divs the text component rendered, once the DOM has
  // caught up, and again whenever the annotations change. The selectors have to
  // match your markup, or nothing is found.
  $effect(() => {
    annotations;
    tick().then(() => {
      const parent = container?.closest(containerClass);
      annotationEls = parent ? Array.from(parent.querySelectorAll(annotationClass)) : [];
    });
  });

  /**
   * @param {number} i The annotation's index.
   * @param {Arrow} arrow
   */
  function getArrowPath(i, arrow) {
    const el = annotationEls[i];
    if (!el) return '';

    // Work out where the arrow starts: the spot on the annotation div named
    // by `source.anchor`, plus any offset
    const arrowSource = getElPosition(el);
    const sourceCoords = arrow.source.anchor.split('-').map((q, j) => {
      const { css, dimension, position } = lookups[j];
      // 'middle' is halfway along the side. Anything else names an edge of the box.
      const point =
        q === 'middle'
          ? arrowSource[css] + arrowSource[dimension] / 2
          : arrowSource[/** @type {'left'|'right'|'top'|'bottom'} */ (q)];
      return (
        point +
        parseCssValue(arrow.source[`d${position}`], j, arrowSource.width, arrowSource.height)
      );
    });

    // Default to clockwise
    const clockwise = typeof arrow.clockwise === 'undefined' ? true : arrow.clockwise;

    // Work out where the arrow ends. A percentage string like '50%' is
    // measured against the chart. Anything else is a data value that goes
    // through the x and y scales.
    const targetCoords = [
      arrow.target.x || k.x(arrow.target),
      arrow.target.y || k.y(arrow.target)
    ].map((q, j) => {
      const val =
        typeof q === 'string' && q.includes('%')
          ? parseCssValue(q, j, k.width, k.height)
          : j
            ? k.yScale(q)
            : k.xScale(q);
      return val + parseCssValue(arrow.target[`d${lookups[j].position}`], j, k.width, k.height);
    });

    // Draw the arc from source to target
    const arc = swoopyArrow();
    arc.angle(Math.PI / 2);
    arc.clockwise(clockwise);
    arc.x(q => q[0]);
    arc.y(q => q[1]);
    return arc([sourceCoords, targetCoords]);
  }
</script>

<g bind:this={container}>
  {#if annotations.length}
    <g class="swoops">
      {#each annotations as anno, i}
        {#if anno.arrows}
          {#each anno.arrows as arrow}
            <path marker-end="url(#arrowhead)" d={getArrowPath(i, arrow)}></path>
          {/each}
        {/if}
      {/each}
    </g>
  {/if}
</g>

<style>
  .swoops {
    position: absolute;
    max-width: 200px;
    line-height: 14px;
  }
  .swoops path {
    fill: none;
    stroke: #000;
    stroke-width: 1;
  }
</style>

// Helper functions for creating swoopy arrows

/**
 * Turn a length into a number of pixels. A number is returned as is. `'12px'`
 * becomes 12. `'50%'` is measured against the chart size. `i` says which side
 * to measure against: 0 for width and 1 for height, the same order as [x, y].
 * @param {string|number|null|undefined} d
 * @param {number} i
 * @param {number} width
 * @param {number} height
 * @returns {number}
 */
export function parseCssValue(d, i, width, height) {
  if (!d) return 0;
  if (typeof d === 'number') {
    return d;
  }
  if (d.indexOf('%') > -1) {
    return (+d.replace('%', '') / 100) * (i ? height : width);
  }
  return +d.replace('px', '');
}

/**
 * Find where an element sits inside its parent. That's the spot an arrow points
 * at. getBoundingClientRect measures from the top of the page, so subtract the
 * parent's position to get coordinates the arrows can use.
 * @param {Element} el
 * @returns {{ top: number, right: number, bottom: number, left: number, width: number, height: number }}
 */
export function getElPosition(el) {
  const annotationBbox = el.getBoundingClientRect();
  const parentBbox = (el.parentElement ?? el).getBoundingClientRect();
  const coords = {
    top: annotationBbox.top - parentBbox.top,
    right: annotationBbox.right - parentBbox.left,
    bottom: annotationBbox.bottom - parentBbox.top,
    left: annotationBbox.left - parentBbox.left,
    width: annotationBbox.width,
    height: annotationBbox.height
  };
  return coords;
}

// Draws the curved arrow itself. Adapted from bizweekgraphics/swoopyarrows.
export function swoopyArrow() {
  let angle = Math.PI;
  let clockwise = true;
  /** @type {(d: any) => number} */
  let xValue = d => d[0];
  /** @type {(d: any) => number} */
  let yValue = d => d[1];

  /**
   * @param {number} a
   * @param {number} b
   * @returns {number}
   */
  function hypotenuse(a, b) {
    return Math.sqrt(Math.pow(a, 2) + Math.pow(b, 2));
  }

  /**
   * @param {any[]} data
   * @returns {string}
   */
  function render(data) {
    data = data.map(d => {
      return [xValue(d), yValue(d)];
    });

    // The arrow is a piece of a circle. The next three lines work out which
    // circle. Start with the straight-line distance between the two points.
    // The arc bows away from that line.
    const h = hypotenuse(data[1][0] - data[0][0], data[1][1] - data[0][1]);

    // How far the circle's center sits from that straight line. A wider
    // `angle` means a flatter arc and a center that sits further back.
    const d = h / (2 * Math.tan(angle / 2));

    // The distance from the center to either endpoint is the circle's radius.
    const r = hypotenuse(d, h / 2);

    // Write the arc out as an SVG path. Here is what each part of an example
    // path `M 200,50 a 50,50 0 0,1 100,0` means:
    //
    //   M 200,50   start at (200,50)
    //   a          draw an arc
    //     50,50    the two radii. Equal radii make it a circle
    //     0        the x-axis rotation. It has no effect on a circle
    //     0,1      large-arc-flag 0 and sweep-flag 1: take the short way, clockwise
    //     100,0    end 100 to the right and level with the start, at (300,50)
    //
    // Full syntax: http://www.w3.org/TR/SVG/paths.html#PathDataEllipticalArcCommands
    const path =
      'M ' +
      data[0][0] +
      ',' +
      data[0][1] +
      ' a ' +
      r +
      ',' +
      r +
      ' 0 0,' +
      (clockwise ? '1' : '0') +
      ' ' +
      (data[1][0] - data[0][0]) +
      ',' +
      (data[1][1] - data[0][1]);

    return path;
  }

  /** @param {number} [_] */
  render.angle = function renderAngle(_) {
    if (!arguments.length) return angle;
    angle = Math.min(Math.max(/** @type {number} */ (_), 1e-6), Math.PI - 1e-6);
    return render;
  };

  /** @param {boolean} [_] */
  render.clockwise = function renderClockwise(_) {
    if (!arguments.length) return clockwise;
    clockwise = !!_;
    return render;
  };

  /** @param {(d: any) => number} [_] */
  render.x = function renderX(_) {
    if (!arguments.length) return xValue;
    xValue = /** @type {(d: any) => number} */ (_);
    return render;
  };

  /** @param {(d: any) => number} [_] */
  render.y = function renderY(_) {
    if (!arguments.length) return yValue;
    yValue = /** @type {(d: any) => number} */ (_);
    return render;
  };

  return render;
}