@mhkeller/layercake-annotations 0.1.0

package/dist/components/AnnotationEditor.svelte

@@ -0,0 +1,127 @@
+<script>
+	/** @typedef {import('../types.js').ModifyAnnotationFn} ModifyAnnotationFn */
+
+	import { getContext } from 'svelte';
+
+	import Draggable from './Draggable.svelte';
+	import EditableText from './EditableText.svelte';
+	import ResizeHandles from './ResizeHandles.svelte';
+	import ArrowZone from './ArrowZone.svelte';
+
+	import invertScale from '../modules/invertScale.js';
+	import filterObject from '../modules/filterObject.js';
+
+	let { d, containerClass } = $props();
+
+	/**
+	 * Layer Cake configuration
+	 */
+	const { config, xScale, yScale, xGet, yGet, percentRange } = getContext('LayerCake');
+	let units = $derived($percentRange === true ? '%' : 'px');
+
+	/**
+	 * State variables
+	 */
+	let isEditable = $state(false);
+	let noteDimensions = $state([0, 0]);
+	// svelte-ignore state_referenced_locally
+	let width = $state(d.width);
+
+	/**
+	 * Arrow sides - simplified to just west and east
+	 */
+	const arrowSides = ['west', 'east'];
+
+	/**
+	 * Context variables
+	 * @type {ModifyAnnotationFn}
+	 */
+	const modifyAnnotation = getContext('modifyAnnotation');
+
+	/**
+	 * Coordinates
+	 */
+	let left = $derived(`calc(${$xGet(d)}${units} + ${d.dx}%)`);
+	let top = $derived(`calc(${$yGet(d)}${units} + ${d.dy}%)`);
+
+	/**
+	 * @param {Array} [position] - The x and y pixel coordinates of the draggable element.
+	 */
+	async function ondrag(position = []) {
+		const [x, y] = position;
+		const xVal = x ? invertScale($xScale, x) : [];
+		const yVal = y ? invertScale($yScale, y) : [];
+
+		const newProps = filterObject(
+			{
+				[$config.x]: xVal[0],
+				[$config.y]: yVal[0],
+				dx: xVal[1],
+				dy: yVal[1]
+			},
+			(d) => d !== undefined
+		);
+
+		// Always save current width
+		if (width) {
+			newProps.width = width;
+		}
+
+		modifyAnnotation(d.id, newProps);
+	}
+
+	/**
+	 * Text alignment - initialized from data, saved on change
+	 * Cmd+click cycles: left → center → right → left
+	 */
+	// svelte-ignore state_referenced_locally
+	let alignment = $state(d.align || 'left');
+
+	function onclick(e) {
+		if (e.metaKey) {
+			let newAlignment;
+			if (alignment === 'left') {
+				newAlignment = 'center';
+			} else if (alignment === 'center') {
+				newAlignment = 'right';
+			} else {
+				newAlignment = 'left';
+			}
+			alignment = newAlignment;
+			modifyAnnotation(d.id, { align: newAlignment });
+		}
+	}
+
+	const grabbers = ['west', 'east'];
+</script>
+
+{#if d}
+	<Draggable
+		id={d.id}
+		{left}
+		{top}
+		{ondrag}
+		{width}
+		{onclick}
+		canDrag={!isEditable}
+		bannedTargets={['arrow-zone']}
+		bind:noteDimensions
+		{containerClass}
+	>
+		<div class="layercake-annotation" data-id={d.id}>
+			<EditableText bind:text={d.text} bind:isEditable {alignment} />
+		</div>
+		<ResizeHandles bind:width {ondrag} {grabbers} {containerClass} />
+	</Draggable>
+
+	{#each arrowSides as side}
+		<ArrowZone {d} {side} {noteDimensions} />
+	{/each}
+{/if}
+
+<style>
+	.layercake-annotation {
+		width: 100%;
+		height: 100%;
+	}
+</style>

package/dist/components/AnnotationEditor.svelte.d.ts

@@ -0,0 +1,14 @@
+export default AnnotationEditor;
+export type ModifyAnnotationFn = import("../types.js").ModifyAnnotationFn;
+type AnnotationEditor = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+declare const AnnotationEditor: import("svelte").Component<{
+    d: any;
+    containerClass: any;
+}, {}, "">;
+type $$ComponentProps = {
+    d: any;
+    containerClass: any;
+};

package/dist/components/AnnotationsData.svelte

@@ -0,0 +1,56 @@
+<!--
+  @component
+  Adds text annotations that get their x and y placement using the `xScale` and `yScale`.
+ -->
+<script>
+	/** @typedef {import('../types.js').Annotation} Annotation */
+
+	import { getContext } from 'svelte';
+
+	const { xGet, yGet, percentRange } = getContext('LayerCake');
+
+	/** @type {{ annotations?: Annotation[], getText?: (d: Annotation) => string }} */
+	let { annotations = $bindable([]), getText = (d) => d.text } = $props();
+
+	let units = $derived($percentRange === true ? '%' : 'px');
+</script>
+
+<div class="layercake-annotations">
+	{#each annotations as d, i}
+		<!-- Wrapper mirrors Draggable structure -->
+		<div
+			class="static-wrapper"
+			data-id={i}
+			style:left={`calc(${$xGet(d)}${units} + ${d.dx || 0}%)`}
+			style:top={`calc(${$yGet(d)}${units} + ${d.dy || 0}%)`}
+			style:width={d.width}
+		>
+			<div class="layercake-annotation" style:text-align={d.align || 'left'}>
+				<pre>{getText(d)}</pre>
+			</div>
+		</div>
+	{/each}
+</div>
+
+<style>
+	/* Mirrors Draggable.svelte CSS exactly */
+	.static-wrapper {
+		position: absolute;
+		display: inline-block;
+		box-sizing: border-box;
+		transition: border-color 250ms;
+		border-radius: 2px;
+		padding: 3px;
+		border: 1px solid transparent;
+	}
+	.layercake-annotation {
+		width: 100%;
+		height: 100%;
+	}
+	pre {
+		margin: 0;
+		font-family: inherit;
+		white-space: pre-wrap;
+		word-wrap: break-word;
+	}
+</style>

package/dist/components/AnnotationsData.svelte.d.ts

@@ -0,0 +1,15 @@
+export default AnnotationsData;
+export type Annotation = import("../types.js").Annotation;
+type AnnotationsData = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/** Adds text annotations that get their x and y placement using the `xScale` and `yScale`. */
+declare const AnnotationsData: import("svelte").Component<{
+    annotations?: Annotation[];
+    getText?: (d: Annotation) => string;
+}, {}, "annotations">;
+type $$ComponentProps = {
+    annotations?: Annotation[];
+    getText?: (d: Annotation) => string;
+};

package/dist/components/ArrowZone.svelte

@@ -0,0 +1,366 @@
+<!--
+  @component
+  Draggable zones for creating/editing arrows. Only supports "west" and "east" sides.
+  - When no arrow exists: shows one handle at annotation edge to create arrow
+  - When arrow exists: shows TWO handles - one at source, one at target
+  Updates arrow position in real-time during drag.
+-->
+<script>
+	/** @typedef {import('../types.js').HoverState} HoverState */
+	/** @typedef {import('../types.js').DragState} DragState */
+	/** @typedef {import('../types.js').SetArrowFn} SetArrowFn */
+	/** @typedef {import('../types.js').ModifyArrowFn} ModifyArrowFn */
+	/** @typedef {import('../types.js').ModifyAnnotationFn} ModifyAnnotationFn */
+	/**
+	 * @template T
+	 * @typedef {import('../types.js').Ref<T>} Ref
+	 */
+
+	import { getContext } from 'svelte';
+	import invertScale from '../modules/invertScale.js';
+	import {
+		getAnnotationBox,
+		getArrowSource,
+		getArrowTarget,
+		calculateSourceDx,
+		calculateSourceDy,
+		HANDLE_OFFSET_PX
+	} from '../modules/coordinates.js';
+
+	const { xScale, yScale, x, y, config, width, height } = getContext('LayerCake');
+
+	let { d, side, noteDimensions } = $props();
+
+	/** @type {Ref<HoverState | null>} */
+	const hovering = getContext('hovering');
+	/** @type {SetArrowFn} */
+	const setArrow = getContext('setArrow');
+	/** @type {ModifyArrowFn} */
+	const modifyArrow = getContext('modifyArrow');
+	/** @type {ModifyAnnotationFn} */
+	const modifyAnnotation = getContext('modifyAnnotation');
+	/** @type {Ref<boolean>} */
+	const moving = getContext('moving');
+	/** @type {Ref<DragState | null>} */
+	const dragState = getContext('previewArrow');
+
+	/** Handle diameter in pixels */
+	const diameterPx = 15;
+
+	/** State - which handle is being dragged */
+	let draggingSource = $state(false);
+	let draggingTarget = $state(false);
+	let dragX = $state(null);
+	let dragY = $state(null);
+
+	/** Get the existing arrow for this side (if any) */
+	let arrow = $derived(d.arrows?.find((a) => a.side === side));
+
+	/** Default clockwise direction based on side (null = straight line, so don't use ??) */
+	let clockwise = $derived(
+		arrow?.clockwise !== undefined ? arrow.clockwise : side === 'west' ? false : true
+	);
+
+	/** Build scales object for coordinate utilities */
+	function getScales() {
+		return {
+			xScale: $xScale,
+			yScale: $yScale,
+			x: $x,
+			y: $y,
+			width: $width,
+			height: $height
+		};
+	}
+
+	/** Annotation box position and dimensions */
+	let annoBox = $derived(getAnnotationBox(d, getScales()));
+
+	/** Default source offsets */
+	let defaultSourceDx = $derived(side === 'west' ? -HANDLE_OFFSET_PX : HANDLE_OFFSET_PX);
+	let defaultSourceDy = $derived(noteDimensions[1] / 2);
+
+	/** Current source position in pixels */
+	let sourcePos = $derived.by(() => {
+		if (arrow) {
+			return getArrowSource(d, arrow, getScales(), noteDimensions[1]);
+		}
+		// Default position when no arrow exists
+		const dx = defaultSourceDx;
+		const dy = defaultSourceDy;
+		if (side === 'east') {
+			return { x: annoBox.left + annoBox.width + dx, y: annoBox.top + dy };
+		}
+		return { x: annoBox.left + dx, y: annoBox.top + dy };
+	});
+
+	let sourceX = $derived(sourcePos.x);
+	let sourceY = $derived(sourcePos.y);
+
+	/** Current target position in pixels (when arrow exists) */
+	let targetX = $derived.by(() => {
+		if (!arrow) return sourceX + (side === 'west' ? -50 : 50);
+		return getArrowTarget(arrow, getScales()).x;
+	});
+
+	let targetY = $derived.by(() => {
+		if (!arrow) return sourceY;
+		return getArrowTarget(arrow, getScales()).y;
+	});
+
+	/**
+	 * Zone positions for display
+	 */
+	let sourceDisplayX = $derived(draggingSource ? dragX : sourceX);
+	let sourceDisplayY = $derived(draggingSource ? dragY : sourceY);
+	let targetDisplayX = $derived(draggingTarget ? dragX : targetX);
+	let targetDisplayY = $derived(draggingTarget ? dragY : targetY);
+
+	/**
+	 * Update drag state for live arrow rendering
+	 */
+	function updateDragState() {
+		if (!draggingSource && !draggingTarget) {
+			dragState.value = null;
+			return;
+		}
+
+		dragState.value = {
+			annotationId: d.id,
+			side,
+			sourceX: draggingSource ? dragX : sourceX,
+			sourceY: draggingSource ? dragY : sourceY,
+			targetX: draggingTarget ? dragX : targetX,
+			targetY: draggingTarget ? dragY : targetY,
+			clockwise
+		};
+	}
+
+	/** Toggle clockwise on cmd+click - cycle order depends on side */
+	function onclick(e) {
+		if (!e.metaKey || !arrow) return;
+
+		let newClockwise;
+		if (side === 'east') {
+			// East: clockwise → straight → counter-clockwise → clockwise
+			if (clockwise === true) {
+				newClockwise = null;
+			} else if (clockwise === null) {
+				newClockwise = false;
+			} else {
+				newClockwise = true;
+			}
+		} else {
+			// West: counter-clockwise → straight → clockwise → counter-clockwise
+			if (clockwise === false) {
+				newClockwise = null;
+			} else if (clockwise === null) {
+				newClockwise = true;
+			} else {
+				newClockwise = false;
+			}
+		}
+
+		modifyArrow(d.id, side, { clockwise: newClockwise });
+	}
+
+	/** Start dragging source handle */
+	function onSourceMousedown() {
+		moving.value = true;
+		draggingSource = true;
+		dragX = sourceX;
+		dragY = sourceY;
+		updateDragState();
+	}
+
+	/** Start dragging target handle (or create mode) */
+	function onTargetMousedown() {
+		moving.value = true;
+		draggingTarget = true;
+		dragX = arrow ? targetX : sourceX;
+		dragY = arrow ? targetY : sourceY;
+		updateDragState();
+	}
+
+	/** Track mouse during drag */
+	function onmousemove(e) {
+		if (!draggingSource && !draggingTarget) return;
+
+		dragX += e.movementX;
+		dragY += e.movementY;
+		updateDragState();
+	}
+
+	/** On release, save the arrow */
+	function onmouseup() {
+		// Only process if we were actually dragging
+		if (!draggingSource && !draggingTarget) return;
+
+		const scales = getScales();
+
+		if (draggingSource && dragX !== null && dragY !== null) {
+			// Update source position using shared coordinate utils
+			const newSourceDx = calculateSourceDx(dragX, d, side, scales);
+			const newSourceDy = calculateSourceDy(dragY, d, scales);
+
+			if (arrow) {
+				modifyArrow(d.id, side, {
+					source: { dx: newSourceDx, dy: newSourceDy }
+				});
+			} else {
+				// Creating new arrow - need target too
+				const [targetDataX, targetOffsetX] = invertScale($xScale, targetX);
+				const [targetDataY, targetOffsetY] = invertScale($yScale, targetY);
+
+				setArrow(d.id, {
+					side,
+					clockwise,
+					source: { dx: newSourceDx, dy: newSourceDy },
+					target: {
+						[$config.x]: targetDataX,
+						[$config.y]: targetDataY,
+						dx: targetOffsetX,
+						dy: targetOffsetY
+					}
+				});
+			}
+		}
+
+		if (draggingTarget && dragX !== null && dragY !== null) {
+			// Update target position (convert to data space)
+			const [targetDataX, targetOffsetX] = invertScale($xScale, dragX);
+			const [targetDataY, targetOffsetY] = invertScale($yScale, dragY);
+
+			// Keep existing source or use defaults
+			const existingSourceDx = arrow?.source?.dx ?? defaultSourceDx;
+
+			setArrow(d.id, {
+				side,
+				clockwise,
+				source: {
+					dx: existingSourceDx,
+					dy: arrow?.source?.dy ?? defaultSourceDy
+				},
+				target: {
+					[$config.x]: targetDataX,
+					[$config.y]: targetDataY,
+					dx: targetOffsetX,
+					dy: targetOffsetY
+				}
+			});
+		}
+
+		// Clear state
+		moving.value = false;
+		draggingSource = false;
+		draggingTarget = false;
+		dragX = null;
+		dragY = null;
+		dragState.value = null;
+	}
+
+	function onmouseover(handle) {
+		if (moving.value) return;
+		hovering.value = { annotationId: d.id, type: 'arrow', side, handle };
+	}
+
+	function onmouseout() {
+		if (moving.value) return;
+		hovering.value = null;
+	}
+
+	// Show handles when hovering over ANY part of this annotation (body, any arrow zone)
+	let isAnnotationHovered = $derived(hovering.value?.annotationId === d.id);
+	let isDragging = $derived(draggingSource || draggingTarget);
+</script>
+
+{#if arrow}
+	<!-- Source handle (when arrow exists) -->
+	<div
+		onmousedown={onSourceMousedown}
+		{onclick}
+		onkeydown={(e) => e.key === 'Enter' && onclick(e)}
+		onfocus={() => onmouseover('source')}
+		onblur={onmouseout}
+		onmouseover={() => onmouseover('source')}
+		{onmouseout}
+		role="button"
+		tabindex="0"
+		aria-label="Arrow source handle - Cmd+click to toggle curve direction"
+		class:visible={isAnnotationHovered || isDragging}
+		class:dragging={draggingSource}
+		class="arrow-zone source {side}"
+		style:left="{sourceDisplayX - diameterPx / 2}px"
+		style:top="{sourceDisplayY - diameterPx / 2}px"
+	></div>
+
+	<!-- Target handle (when arrow exists) -->
+	<div
+		onmousedown={onTargetMousedown}
+		{onclick}
+		onkeydown={(e) => e.key === 'Enter' && onclick(e)}
+		onfocus={() => onmouseover('target')}
+		onblur={onmouseout}
+		onmouseover={() => onmouseover('target')}
+		{onmouseout}
+		role="button"
+		tabindex="0"
+		aria-label="Arrow target handle - drag to move arrow endpoint"
+		class:visible={isAnnotationHovered || isDragging}
+		class:dragging={draggingTarget}
+		class="arrow-zone target {side}"
+		style:left="{targetDisplayX - diameterPx / 2}px"
+		style:top="{targetDisplayY - diameterPx / 2}px"
+	></div>
+{:else}
+	<!-- Create handle (no arrow yet) - drag to create -->
+	<div
+		onmousedown={onTargetMousedown}
+		onfocus={() => onmouseover('create')}
+		onblur={onmouseout}
+		onmouseover={() => onmouseover('create')}
+		{onmouseout}
+		role="button"
+		tabindex="0"
+		aria-label="Drag to create arrow"
+		class:visible={isAnnotationHovered || isDragging}
+		class:dragging={draggingTarget}
+		class="arrow-zone create {side}"
+		style:left="{(draggingTarget ? dragX : sourceX) - diameterPx / 2}px"
+		style:top="{(draggingTarget ? dragY : sourceY) - diameterPx / 2}px"
+	></div>
+{/if}
+
+<svelte:window {onmouseup} {onmousemove} />
+
+<style>
+	.arrow-zone {
+		--diameter: 15px;
+		position: absolute;
+		width: var(--diameter);
+		height: var(--diameter);
+		border-radius: 50%;
+		border: 1px dashed #333;
+		background: rgba(0, 0, 0, 0.1);
+		cursor: grab;
+		opacity: 0;
+		transition: opacity 250ms;
+		z-index: 10;
+	}
+	/* Larger hit area for easier hovering */
+	.arrow-zone:before {
+		content: '';
+		position: absolute;
+		width: 21px;
+		height: 23px;
+		top: -5px;
+		left: -3.5px;
+	}
+	.arrow-zone.visible,
+	.arrow-zone.dragging {
+		opacity: 1;
+	}
+	.arrow-zone.dragging {
+		cursor: grabbing;
+	}
+</style>

package/dist/components/ArrowZone.svelte.d.ts

@@ -0,0 +1,27 @@
+export default ArrowZone;
+export type HoverState = import("../types.js").HoverState;
+export type DragState = import("../types.js").DragState;
+export type SetArrowFn = import("../types.js").SetArrowFn;
+export type ModifyArrowFn = import("../types.js").ModifyArrowFn;
+export type ModifyAnnotationFn = import("../types.js").ModifyAnnotationFn;
+export type Ref<T> = import("../types.js").Ref<T>;
+type ArrowZone = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * Draggable zones for creating/editing arrows. Only supports "west" and "east" sides.
+ * - When no arrow exists: shows one handle at annotation edge to create arrow
+ * - When arrow exists: shows TWO handles - one at source, one at target
+ * Updates arrow position in real-time during drag.
+ */
+declare const ArrowZone: import("svelte").Component<{
+    d: any;
+    side: any;
+    noteDimensions: any;
+}, {}, "">;
+type $$ComponentProps = {
+    d: any;
+    side: any;
+    noteDimensions: any;
+};

package/dist/components/ArrowheadMarker.svelte

@@ -0,0 +1,18 @@
+<!--
+  @component
+  Generates an SVG marker containing a marker for a triangle makes a nice arrowhead. Add it to the named slot called "defs" on the SVG layout component.
+ -->
+<script>
+	/** @type {{ fill?: string, stroke?: string }} */
+	let { fill = '#000', stroke = '#000' } = $props();
+</script>
+
+<marker
+	id="layercake-annotation-arrowhead"
+	viewBox="-10 -10 20 20"
+	markerWidth="17"
+	markerHeight="17"
+	orient="auto"
+>
+	<path d="M-6,-6 L 0,0 L -6,6" {fill} {stroke} />
+</marker>

package/dist/components/ArrowheadMarker.svelte.d.ts

@@ -0,0 +1,14 @@
+export default ArrowheadMarker;
+type ArrowheadMarker = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/** Generates an SVG marker containing a marker for a triangle makes a nice arrowhead. Add it to the named slot called "defs" on the SVG layout component. */
+declare const ArrowheadMarker: import("svelte").Component<{
+    fill?: string;
+    stroke?: string;
+}, {}, "">;
+type $$ComponentProps = {
+    fill?: string;
+    stroke?: string;
+};