@mhkeller/layercake-annotations 0.1.0

package/dist/modules/arrowUtils.js

@@ -0,0 +1,32 @@
+/**
+ * Create an SVG arc path between two points.
+ * Adapted from bizweekgraphics/swoopyarrows
+ *
+ * @param {{ x: number, y: number }} source - Start point
+ * @param {{ x: number, y: number }} target - End point
+ * @param {boolean|null} clockwise - Arc direction (null for straight line)
+ * @param {number} [angle=Math.PI/2] - Arc angle in radians
+ * @returns {string} SVG path string
+ */
+export function createArrowPath(source, target, clockwise, angle = Math.PI / 2) {
+	// Straight line if clockwise is null
+	if (clockwise === null) {
+		return `M ${source.x},${source.y} L ${target.x},${target.y}`;
+	}
+
+	// Clamp angle to valid range
+	angle = Math.min(Math.max(angle, 1e-6), Math.PI - 1e-6);
+
+	// Calculate chord length between points
+	const dx = target.x - source.x;
+	const dy = target.y - source.y;
+	const chordLength = Math.sqrt(dx * dx + dy * dy);
+
+	// Calculate arc radius from chord length and angle
+	const distance = chordLength / (2 * Math.tan(angle / 2));
+	const radius = Math.sqrt(distance * distance + (chordLength / 2) * (chordLength / 2));
+
+	// SVG arc command: M x,y a rx,ry rotation large-arc-flag,sweep-flag dx,dy
+	return `M ${source.x},${source.y} a ${radius},${radius} 0 0,${clockwise ? '1' : '0'} ${dx},${dy}`;
+}
+

package/dist/modules/coordinates.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Calculate annotation box position in pixels.
+ *
+ * @param {Object} anno - Annotation object with x/y data values and dx/dy percentage offsets
+ * @param {Object} scales - Object containing LayerCake scales and accessors
+ * @param {Function} scales.xScale - X scale function
+ * @param {Function} scales.yScale - Y scale function
+ * @param {Function} scales.x - X accessor function
+ * @param {Function} scales.y - Y accessor function
+ * @param {number} scales.width - Chart width in pixels
+ * @param {number} scales.height - Chart height in pixels
+ * @returns {{ left: number, top: number, width: number }}
+ */
+export function getAnnotationBox(anno: any, scales: {
+    xScale: Function;
+    yScale: Function;
+    x: Function;
+    y: Function;
+    width: number;
+    height: number;
+}): {
+    left: number;
+    top: number;
+    width: number;
+};
+/**
+ * Calculate arrow source position in pixels.
+ *
+ * @param {Object} anno - Annotation object
+ * @param {Object} arrow - Arrow object with side and source offset
+ * @param {Object} scales - LayerCake scales
+ * @param {number} [annoHeight] - Annotation height for vertical centering (optional)
+ * @returns {{ x: number, y: number }}
+ */
+export function getArrowSource(anno: any, arrow: any, scales: any, annoHeight?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate arrow target position in pixels.
+ *
+ * @param {Object} arrow - Arrow object with target data values
+ * @param {Object} scales - LayerCake scales
+ * @returns {{ x: number, y: number }}
+ */
+export function getArrowTarget(arrow: any, scales: any): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate the source dx value to store when saving an arrow.
+ * Converts pixel position back to offset from annotation edge.
+ *
+ * @param {number} pixelX - Current X position in pixels
+ * @param {Object} anno - Annotation object
+ * @param {string} side - 'east' or 'west'
+ * @param {Object} scales - LayerCake scales
+ * @returns {number} - The dx offset to store
+ */
+export function calculateSourceDx(pixelX: number, anno: any, side: string, scales: any): number;
+/**
+ * Calculate the source dy value to store when saving an arrow.
+ *
+ * @param {number} pixelY - Current Y position in pixels
+ * @param {Object} anno - Annotation object
+ * @param {Object} scales - LayerCake scales
+ * @returns {number} - The dy offset to store
+ */
+export function calculateSourceDy(pixelY: number, anno: any, scales: any): number;
+/**
+ * Shared coordinate calculation utilities for annotations and arrows.
+ *
+ * Coordinate System:
+ * - Annotations are positioned in DATA SPACE (using xScale/yScale)
+ * - dx/dy offsets are PERCENTAGES of chart width/height
+ * - Arrow source dx/dy are PIXEL offsets from annotation edge
+ * - Arrow target is in DATA SPACE with optional percentage offsets
+ *
+ * For east arrows, source dx is relative to RIGHT edge of annotation.
+ * For west arrows, source dx is relative to LEFT edge of annotation.
+ */
+/** Default annotation width in pixels when not explicitly set */
+export const DEFAULT_ANNOTATION_WIDTH: 155;
+/** Default handle offset from annotation edge in pixels */
+export const HANDLE_OFFSET_PX: 12;

package/dist/modules/coordinates.js

@@ -0,0 +1,139 @@
+/**
+ * Shared coordinate calculation utilities for annotations and arrows.
+ *
+ * Coordinate System:
+ * - Annotations are positioned in DATA SPACE (using xScale/yScale)
+ * - dx/dy offsets are PERCENTAGES of chart width/height
+ * - Arrow source dx/dy are PIXEL offsets from annotation edge
+ * - Arrow target is in DATA SPACE with optional percentage offsets
+ *
+ * For east arrows, source dx is relative to RIGHT edge of annotation.
+ * For west arrows, source dx is relative to LEFT edge of annotation.
+ */
+
+/** Default annotation width in pixels when not explicitly set */
+export const DEFAULT_ANNOTATION_WIDTH = 155;
+
+/** Default handle offset from annotation edge in pixels */
+export const HANDLE_OFFSET_PX = 12;
+
+/**
+ * Calculate annotation box position in pixels.
+ *
+ * @param {Object} anno - Annotation object with x/y data values and dx/dy percentage offsets
+ * @param {Object} scales - Object containing LayerCake scales and accessors
+ * @param {Function} scales.xScale - X scale function
+ * @param {Function} scales.yScale - Y scale function
+ * @param {Function} scales.x - X accessor function
+ * @param {Function} scales.y - Y accessor function
+ * @param {number} scales.width - Chart width in pixels
+ * @param {number} scales.height - Chart height in pixels
+ * @returns {{ left: number, top: number, width: number }}
+ */
+export function getAnnotationBox(anno, scales) {
+	const { xScale, yScale, x, y, width, height } = scales;
+
+	// Convert percentage offsets to pixels
+	const offsetX = ((anno.dx ?? 0) / 100) * width;
+	const offsetY = ((anno.dy ?? 0) / 100) * height;
+
+	// Calculate top-left position
+	const left = xScale(x(anno)) + offsetX;
+	const top = yScale(y(anno)) + offsetY;
+
+	// Get width (stored as "150px" string or use default)
+	const annoWidth = anno.width ? parseInt(anno.width) : DEFAULT_ANNOTATION_WIDTH;
+
+	return { left, top, width: annoWidth };
+}
+
+/**
+ * Calculate arrow source position in pixels.
+ *
+ * @param {Object} anno - Annotation object
+ * @param {Object} arrow - Arrow object with side and source offset
+ * @param {Object} scales - LayerCake scales
+ * @param {number} [annoHeight] - Annotation height for vertical centering (optional)
+ * @returns {{ x: number, y: number }}
+ */
+export function getArrowSource(anno, arrow, scales, annoHeight = 0) {
+	const box = getAnnotationBox(anno, scales);
+
+	// Default offsets when no arrow source is specified
+	const defaultDx = arrow.side === 'west' ? -HANDLE_OFFSET_PX : HANDLE_OFFSET_PX;
+	const defaultDy = annoHeight / 2;
+
+	const dx = arrow.source?.dx ?? defaultDx;
+	const dy = arrow.source?.dy ?? defaultDy;
+
+	let x;
+	if (arrow.side === 'east') {
+		// East arrow: offset from right edge
+		x = box.left + box.width + dx;
+	} else {
+		// West arrow: offset from left edge
+		x = box.left + dx;
+	}
+
+	const y = box.top + dy;
+
+	return { x, y };
+}
+
+/**
+ * Calculate arrow target position in pixels.
+ *
+ * @param {Object} arrow - Arrow object with target data values
+ * @param {Object} scales - LayerCake scales
+ * @returns {{ x: number, y: number }}
+ */
+export function getArrowTarget(arrow, scales) {
+	const { xScale, yScale, x, y, width, height } = scales;
+
+	// Target is in data space
+	const baseX = xScale(x(arrow.target));
+	const baseY = yScale(y(arrow.target));
+
+	// Add percentage offsets (used for ordinal scales)
+	const offsetX = ((arrow.target?.dx ?? 0) / 100) * width;
+	const offsetY = ((arrow.target?.dy ?? 0) / 100) * height;
+
+	return {
+		x: baseX + offsetX,
+		y: baseY + offsetY
+	};
+}
+
+/**
+ * Calculate the source dx value to store when saving an arrow.
+ * Converts pixel position back to offset from annotation edge.
+ *
+ * @param {number} pixelX - Current X position in pixels
+ * @param {Object} anno - Annotation object
+ * @param {string} side - 'east' or 'west'
+ * @param {Object} scales - LayerCake scales
+ * @returns {number} - The dx offset to store
+ */
+export function calculateSourceDx(pixelX, anno, side, scales) {
+	const box = getAnnotationBox(anno, scales);
+
+	if (side === 'east') {
+		// dx is offset from right edge
+		return pixelX - (box.left + box.width);
+	}
+	// dx is offset from left edge
+	return pixelX - box.left;
+}
+
+/**
+ * Calculate the source dy value to store when saving an arrow.
+ *
+ * @param {number} pixelY - Current Y position in pixels
+ * @param {Object} anno - Annotation object
+ * @param {Object} scales - LayerCake scales
+ * @returns {number} - The dy offset to store
+ */
+export function calculateSourceDy(pixelY, anno, scales) {
+	const box = getAnnotationBox(anno, scales);
+	return pixelY - box.top;
+}

package/dist/modules/createRef.svelte.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Create a state reference that can be passed between components.
+ * @template T
+ * @param {T} [data]
+ * @returns {import('../types.js').Ref<T>}
+ */
+export default function createRef<T>(data?: T): import("../types.js").Ref<T>;

package/dist/modules/createRef.svelte.js

@@ -0,0 +1,10 @@
+/**
+ * Create a state reference that can be passed between components.
+ * @template T
+ * @param {T} [data]
+ * @returns {import('../types.js').Ref<T>}
+ */
+export default function createRef(data) {
+	let state = $state({ value: data });
+	return state;
+}

package/dist/modules/filterObject.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Filters an object by a predicate function.
+ * @param {Object} obj - The object to filter.
+ * @param {Function} predicate - The predicate function.
+ * @returns {Object} - The filtered object.
+ */
+export default function filterObject(obj: any, predicate: Function): any;

package/dist/modules/filterObject.js

@@ -0,0 +1,14 @@
+/**
+ * Filters an object by a predicate function.
+ * @param {Object} obj - The object to filter.
+ * @param {Function} predicate - The predicate function.
+ * @returns {Object} - The filtered object.
+ */
+export default function filterObject(obj, predicate) {
+	return Object.keys(obj).reduce((acc, key) => {
+		if (predicate(obj[key])) {
+			acc[key] = obj[key];
+		}
+		return acc;
+	}, {});
+}

package/dist/modules/invertScale.d.ts

@@ -0,0 +1 @@
+export default function invertScale(scale: any, pos: any): any[];

package/dist/modules/invertScale.js

@@ -0,0 +1,5 @@
+import ordinalInvert from './ordinalInvert.js';
+
+export default function invertScale(scale, pos) {
+	return scale.invert ? [scale.invert(pos), 0] : ordinalInvert(scale, pos);
+}

package/dist/modules/newAnnotation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Create a new annotation at the click position
+ * @param {MouseEvent} e - Click event
+ * @param {number} id - Unique identifier
+ * @param {Object} options - LayerCake scales and config
+ * @returns {Annotation}
+ */
+export default function newAnnotation(e: MouseEvent, id: number, { xScale, yScale, config }: any): Annotation;
+export type Annotation = import("../types.js").Annotation;

package/dist/modules/newAnnotation.js

@@ -0,0 +1,26 @@
+/** @typedef {import('../types.js').Annotation} Annotation */
+
+import invertScale from './invertScale.js';
+
+/**
+ * Create a new annotation at the click position
+ * @param {MouseEvent} e - Click event
+ * @param {number} id - Unique identifier
+ * @param {Object} options - LayerCake scales and config
+ * @returns {Annotation}
+ */
+export default function newAnnotation(e, id, { xScale, yScale, config }) {
+	const xVal = invertScale(xScale, e.offsetX);
+	const yVal = invertScale(yScale, e.offsetY);
+
+	return {
+		id,
+		[config.x]: xVal[0],
+		[config.y]: yVal[0],
+		dx: xVal[1],
+		dy: yVal[1],
+		text: 'Enter your note here...',
+		width: '168px',
+		arrows: []
+	};
+}

package/dist/modules/ordinalInvert.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Find the domain value at a given position.
+ * https://stackoverflow.com/questions/20758373/inversion-with-ordinal-scale/30743306#30743306
+ *
+ * @param {d3.scale} scale - The d3 scale to invert.
+ * @param {number} pos - The position to invert.
+ * @returns {Array} - The domain value and offset.
+ */
+export default function ordinalInvert(scale: d3.scale, pos: number): any[];

package/dist/modules/ordinalInvert.js

@@ -0,0 +1,22 @@
+/**
+ * Find the domain value at a given position.
+ * https://stackoverflow.com/questions/20758373/inversion-with-ordinal-scale/30743306#30743306
+ *
+ * @param {d3.scale} scale - The d3 scale to invert.
+ * @param {number} pos - The position to invert.
+ * @returns {Array} - The domain value and offset.
+ */
+export default function ordinalInvert(scale, pos) {
+	let previous = null;
+	let domain = scale.domain();
+	let offset = 0;
+
+	for (let dm of domain) {
+		if (scale(dm) > pos) {
+			return [previous, offset];
+		}
+		previous = dm;
+		offset = ((pos - scale(dm)) / Math.max(...scale.range())) * 100;
+	}
+	return [previous, offset];
+}

package/dist/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Type definitions for layercake-annotations
+ */
+
+/**
+ * Arrow source position (pixel offsets from annotation edge)
+ */
+export interface ArrowSource {
+	/** X offset in pixels from annotation edge (west=left, east=right) */
+	dx: number;
+	/** Y offset in pixels from annotation top */
+	dy: number;
+}
+
+/**
+ * Arrow target position (data space coordinates)
+ */
+export interface ArrowTarget {
+	/** X data value (key varies based on LayerCake config) */
+	[xKey: string]: unknown;
+	/** Y data value (key varies based on LayerCake config) */
+	/** Percentage offset for ordinal X scales (0-100) */
+	dx?: number;
+	/** Percentage offset for ordinal Y scales (0-100) */
+	dy?: number;
+}
+
+/**
+ * Arrow definition
+ */
+export interface Arrow {
+	/** Which side of annotation: 'west' or 'east' */
+	side: 'west' | 'east';
+	/** Arc direction: true=clockwise, false=counter-clockwise, null=straight line */
+	clockwise: boolean | null;
+	/** Source position (pixel offsets from annotation) */
+	source: ArrowSource;
+	/** Target position (data coordinates) */
+	target: ArrowTarget;
+}
+
+/**
+ * Annotation definition
+ */
+export interface Annotation {
+	/** Unique identifier */
+	id: number;
+	/** X data value (key varies based on LayerCake config, e.g., 'date' or 'x') */
+	[xKey: string]: unknown;
+	/** Y data value (key varies based on LayerCake config, e.g., 'value' or 'y') */
+	/** Percentage offset from data point in X direction */
+	dx: number;
+	/** Percentage offset from data point in Y direction */
+	dy: number;
+	/** Annotation text content */
+	text: string;
+	/** Width of annotation box (e.g., "150px") */
+	width?: string;
+	/** Text alignment: 'left', 'center', or 'right' */
+	align?: 'left' | 'center' | 'right';
+	/** Arrows attached to this annotation */
+	arrows: Arrow[];
+}
+
+/**
+ * Hovering state for interactions
+ */
+export interface HoverState {
+	/** ID of the annotation being hovered */
+	annotationId: number;
+	/** What is being hovered: 'body' for annotation text, 'arrow' for arrow handles */
+	type: 'body' | 'arrow';
+	/** For arrow hovers: which side ('west' or 'east') */
+	side?: 'west' | 'east';
+	/** For arrow hovers: which handle ('source', 'target', or 'create') */
+	handle?: 'source' | 'target' | 'create';
+}
+
+/**
+ * Drag state for live arrow preview during dragging
+ */
+export interface DragState {
+	/** ID of the annotation being edited */
+	annotationId: number;
+	/** Which arrow side is being dragged */
+	side: 'west' | 'east';
+	/** Current source X position in pixels */
+	sourceX: number;
+	/** Current source Y position in pixels */
+	sourceY: number;
+	/** Current target X position in pixels */
+	targetX: number;
+	/** Current target Y position in pixels */
+	targetY: number;
+	/** Arc direction */
+	clockwise: boolean | null;
+}
+
+/**
+ * LayerCake scales object passed to coordinate utilities
+ */
+export interface LayerCakeScales {
+	/** X scale function (data -> pixels) */
+	xScale: (value: unknown) => number;
+	/** Y scale function (data -> pixels) */
+	yScale: (value: unknown) => number;
+	/** X accessor function */
+	x: (d: unknown) => unknown;
+	/** Y accessor function */
+	y: (d: unknown) => unknown;
+	/** Chart width in pixels */
+	width: number;
+	/** Chart height in pixels */
+	height: number;
+}
+
+/**
+ * Annotation box position and dimensions
+ */
+export interface AnnotationBox {
+	/** Left edge position in pixels */
+	left: number;
+	/** Top edge position in pixels */
+	top: number;
+	/** Width in pixels */
+	width: number;
+}
+
+/**
+ * Point coordinates
+ */
+export interface Point {
+	x: number;
+	y: number;
+}
+
+/**
+ * Reactive reference wrapper (from createRef)
+ */
+export interface Ref<T> {
+	value: T;
+}
+
+/**
+ * Function to modify annotation properties
+ */
+export type ModifyAnnotationFn = (id: number, newProps: Partial<Annotation>) => void;
+
+/**
+ * Function to create or update an arrow
+ */
+export type SetArrowFn = (id: number, arrow: Arrow) => void;
+
+/**
+ * Function to modify arrow properties
+ */
+export type ModifyArrowFn = (id: number, side: 'west' | 'east', attrs: Partial<Arrow>) => void;
+
+/**
+ * Function to save annotation config (provided by parent)
+ */
+export type SaveAnnotationConfigFn = (annotations: Annotation[]) => void;

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "@mhkeller/layercake-annotations",
+	"version": "0.1.0",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build && pnpm package",
+		"preview": "vite preview",
+		"package": "svelte-kit sync && svelte-package -o dist && publint",
+		"prepublishOnly": "pnpm package",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json --watch",
+		"lint": "prettier --check .",
+		"format": "prettier --write .",
+		"test": "playwright test",
+		"test:ui": "playwright test --ui",
+		"test:update": "playwright test --update-snapshots"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		},
+		"./types": {
+			"types": "./dist/types.d.ts"
+		}
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*"
+	],
+	"peerDependencies": {
+		"svelte": "^5.0.0"
+	},
+	"devDependencies": {
+		"@playwright/test": "^1.57.0",
+		"@rollup/plugin-dsv": "^3.0.4",
+		"@sveltejs/adapter-auto": "^3.0.0",
+		"@sveltejs/kit": "^2.0.0",
+		"@sveltejs/package": "^2.0.0",
+		"@sveltejs/vite-plugin-svelte": "^4.0.0-next.6",
+		"d3-scale": "^4.0.2",
+		"prettier": "^3.1.1",
+		"prettier-plugin-svelte": "^3.1.2",
+		"publint": "^0.2.0",
+		"svelte": "^5.0.0",
+		"svelte-check": "^4.0.0",
+		"typescript": "^5.0.0",
+		"vite": "^5.0.11"
+	},
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"layercake": "^10.0.2",
+		"underscore": "^1.13.7"
+	}
+}