@mhkeller/layercake-annotations 0.1.0

package/README.md

@@ -0,0 +1,184 @@
+# LayerCake Annotations
+
+Add interactive text annotations with swoopy arrows to [LayerCake](https://layercake.graphics) charts.
+
+## Installation
+
+```sh
+pnpm add @mhkeller/layercake-annotations
+```
+
+## Quick Start
+
+```svelte
+<script>
+  import { LayerCake } from 'layercake';
+  import { Annotations } from '@mhkeller/layercake-annotations';
+
+  let annotations = $state([]);
+</script>
+
+<LayerCake data={data} x="date" y="value">
+  <Annotations bind:annotations />
+</LayerCake>
+```
+
+**Creating annotations:**
+- Click anywhere on the chart to create
+- Drag to reposition
+- Double-click text to edit
+- Hover + Delete/Backspace to remove
+
+**Editing text:**
+- Double-click to edit
+- Enter to save
+- Shift+Enter for line breaks
+- Escape to cancel
+
+**Formatting:**
+- Cmd+click annotation to cycle text alignment: left → center → right
+
+**Creating arrows:**
+- Hover over annotation to reveal handles on west/east edges
+- Drag a handle outward to create an arrow
+- Cmd+click arrow to cycle through: curved clockwise → straight → curved counter-clockwise
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `annotations` | `Annotation[]` | `[]` | Array of annotation objects (bindable) |
+| `editable` | `boolean` | `true` | Enable editing. Set `false` for read-only display |
+
+## Annotation Data Structure
+
+```js
+{
+  id: 0,                           // Unique identifier
+  date: new Date('2024-03-15'),    // X value (matches LayerCake x accessor)
+  value: 42,                       // Y value (matches LayerCake y accessor)
+  dx: 5,                           // X offset: percentage of chart width (-100 to 100)
+  dy: -10,                         // Y offset: percentage of chart height (-100 to 100)
+  text: 'Peak value',              // Annotation text (supports line breaks)
+  width: '120px',                  // Optional: fixed width
+  align: 'left',                   // Optional: 'left', 'center', or 'right'
+  arrows: []                       // Array of arrows (see below)
+}
+```
+
+### Offsets explained
+
+The `dx` and `dy` values are **percentages of the chart dimensions** (not decimals 0–1).
+
+| Value | Meaning |
+|-------|---------|
+| `dx: 0` | Annotation left edge aligned with data point |
+| `dx: 10` | Shifted right by 10% of chart width |
+| `dx: -5` | Shifted left by 5% of chart width |
+| `dy: -15` | Shifted up by 15% of chart height |
+
+### Arrow structure
+
+```js
+{
+  side: 'east',                    // 'west' or 'east' - which side of annotation
+  clockwise: true,                 // true = clockwise curve, false = counter-clockwise, null = straight
+  source: { 
+    dx: 12,                        // Pixels from annotation edge (horizontal)
+    dy: 15                         // Pixels from annotation center (vertical)
+  },
+  target: { 
+    date: new Date('2024-03-15'),  // X data value (matches LayerCake x accessor)
+    value: 42,                     // Y data value
+    dx: 0,                         // % offset for ordinal X scales (0-100)
+    dy: 0                          // % offset for ordinal Y scales (0-100)
+  }
+}
+```
+
+## Full Example
+
+```svelte
+<script>
+  import { LayerCake, Svg, Html } from 'layercake';
+  import { Annotations } from '@mhkeller/layercake-annotations';
+  import Line from './Line.svelte';
+
+  let data = [...];
+  let annotations = $state([
+    {
+      id: 0,
+      date: new Date('2024-06-01'),
+      value: 150,
+      dx: 2,
+      dy: -8,
+      text: 'Summer peak',
+      width: '100px',
+      arrows: [{
+        side: 'west',
+        clockwise: false,
+        source: { dx: -12, dy: 0 },
+        target: { date: new Date('2024-06-01'), value: 150, dx: 0, dy: 0 }
+      }]
+    }
+  ]);
+  
+  let editable = $state(true);
+</script>
+
+<label>
+  <input type="checkbox" bind:checked={editable} /> Edit mode
+</label>
+
+<div class="chart-container">
+  <LayerCake {data} x="date" y="value">
+    <Svg><Line /></Svg>
+    <Annotations bind:annotations {editable} />
+  </LayerCake>
+</div>
+```
+
+## TypeScript
+
+```ts
+import type { Annotation, Arrow } from '@mhkeller/layercake-annotations/types';
+```
+
+## Components
+
+| Export | Description |
+|--------|-------------|
+| `Annotations` | Main component – set `editable` prop to toggle modes |
+| `AnnotationsEditor` | Edit mode only |
+| `AnnotationsStatic` | Read-only mode only |
+
+## Development
+
+```sh
+pnpm install
+pnpm dev          # Start dev server at localhost:5173
+pnpm test         # Run Playwright visual regression tests
+pnpm package      # Build for npm distribution
+```
+
+## Architecture
+
+```
+src/lib/
+├── Annotations.svelte        # Wrapper: switches Editor/Static based on editable
+├── Editor.svelte             # Edit mode: state management, context providers
+├── Static.svelte             # Read-only: renders annotations + arrows
+├── components/
+│   ├── AnnotationEditor      # Draggable annotation with text editing
+│   ├── AnnotationsData       # Static annotation renderer
+│   ├── ArrowZone             # Handles for creating/editing arrows
+│   ├── Arrows                # SVG arrow path rendering
+│   ├── Draggable             # Drag behavior wrapper
+│   ├── EditableText          # Contenteditable text input
+│   └── ResizeHandles         # Width resize handles
+├── modules/
+│   ├── coordinates.js        # Position calculations
+│   ├── invertScale.js        # Pixel → data value conversion
+│   └── arrowUtils.js         # SVG arc path generation
+└── types.d.ts                # TypeScript definitions
+```

package/dist/Annotations.svelte

@@ -0,0 +1,15 @@
+<script>
+	/** @typedef {import('./types.js').Annotation} Annotation */
+
+	import Editor from './Editor.svelte';
+	import Static from './Static.svelte';
+
+	/** @type {{ annotations?: Annotation[], editable?: boolean }} */
+	let { annotations = $bindable([]), editable = true } = $props();
+</script>
+
+{#if editable}
+	<Editor bind:annotations />
+{:else}
+	<Static {annotations} />
+{/if}

package/dist/Annotations.svelte.d.ts

@@ -0,0 +1,14 @@
+export default Annotations;
+export type Annotation = import("./types.js").Annotation;
+type Annotations = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+declare const Annotations: import("svelte").Component<{
+    annotations?: Annotation[];
+    editable?: boolean;
+}, {}, "annotations">;
+type $$ComponentProps = {
+    annotations?: Annotation[];
+    editable?: boolean;
+};

package/dist/Editor.svelte

@@ -0,0 +1,213 @@
+<script>
+	/** @typedef {import('./types.js').Annotation} Annotation */
+	/** @typedef {import('./types.js').Arrow} Arrow */
+	/** @typedef {import('./types.js').HoverState} HoverState */
+	/** @typedef {import('./types.js').DragState} DragState */
+	/** @typedef {import('./types.js').SaveAnnotationConfigFn} SaveAnnotationConfigFn */
+	/**
+	 * @template T
+	 * @typedef {import('./types.js').Ref<T>} Ref
+	 */
+
+	import { getContext, setContext } from 'svelte';
+	import { Svg, Html } from 'layercake';
+	import { debounce } from 'underscore';
+
+	import AnnotationEditor from './components/AnnotationEditor.svelte';
+	import ArrowheadMarker from './components/ArrowheadMarker.svelte';
+	import Arrows from './components/Arrows.svelte';
+
+	import createRef from './modules/createRef.svelte.js';
+	import newAnnotation from './modules/newAnnotation.js';
+
+	/** @type {{ annotations?: Annotation[], containerClass?: string }} */
+	let { annotations: annos = $bindable([]), containerClass } = $props();
+
+	/**
+	 * LayerCake context
+	 */
+	const { xScale, yScale, config } = getContext('LayerCake');
+
+	/** @type {SaveAnnotationConfigFn | undefined} */
+	const saveAnnotationConfig = getContext('saveAnnotationConfig');
+
+	/**
+	 * Save the config and log it for easy copy-paste
+	 */
+	const saveConfig_debounced = debounce((annos) => {
+		console.log('Annotations config:', JSON.stringify(annos, null, 2));
+		if (saveAnnotationConfig) {
+			saveAnnotationConfig(annos);
+		}
+	}, 1_000);
+
+	/**
+	 * State vars
+	 */
+	let idCounter = Math.max(...annos.map((d) => d.id), -1);
+	let annotations = $state(annos);
+
+	/** @type {Ref<boolean>} */
+	const isEditing = createRef(false);
+
+	/** @type {Ref<HoverState | null>} */
+	const hovering = createRef(null);
+
+	/** @type {Ref<boolean>} */
+	const moving = createRef(false);
+
+	/** @type {Ref<DragState | null>} - Preview arrow shown during drag */
+	const previewArrow = createRef(null);
+
+	setContext('isEditing', isEditing);
+	setContext('hovering', hovering);
+	setContext('moving', moving);
+	setContext('previewArrow', previewArrow);
+
+	/**
+	 * Add a new annotation to the chart
+	 */
+	function onclick(e) {
+		if (isEditing.value === true) return;
+
+		const annotation = newAnnotation(e, ++idCounter, {
+			xScale: $xScale,
+			yScale: $yScale,
+			config: $config
+		});
+		annotations.push(annotation);
+		saveConfig_debounced(annotations);
+	}
+
+	/**
+	 * Delete an annotation from the chart
+	 */
+	async function deleteAnnotation(id) {
+		annotations = annotations.filter((d) => d.id !== id);
+		saveConfig_debounced(annotations);
+	}
+
+	/**
+	 * Modify the annotation's coordinates on drag
+	 */
+	function modifyAnnotation(id, newProps) {
+		annotations.forEach((d, i) => {
+			if (d.id === id) {
+				annotations[i] = {
+					...d,
+					...newProps
+				};
+			}
+		});
+		saveConfig_debounced(annotations);
+	}
+
+	/**
+	 * Set or update an arrow on an annotation
+	 * Arrow structure: { side, clockwise, source: { dx, dy }, target: { [xKey], [yKey] } }
+	 */
+	function setArrow(id, arrow) {
+		const annotation = annotations.find((d) => d.id === id);
+		if (!annotation) return;
+
+		const existingIndex = annotation.arrows.findIndex((a) => a.side === arrow.side);
+
+		if (existingIndex >= 0) {
+			annotation.arrows[existingIndex] = arrow;
+		} else {
+			annotation.arrows.push(arrow);
+		}
+
+		saveConfig_debounced(annotations);
+	}
+
+	/**
+	 * Modify an arrow's properties (e.g., clockwise)
+	 */
+	function modifyArrow(id, side, attrs) {
+		const annotation = annotations.find((d) => d.id === id);
+		if (!annotation) return;
+
+		const arrow = annotation.arrows.find((a) => a.side === side);
+		if (!arrow) return;
+
+		Object.assign(arrow, attrs);
+		saveConfig_debounced(annotations);
+	}
+
+	/**
+	 * Delete an arrow from an annotation
+	 */
+	function deleteArrow(id, side) {
+		const annotation = annotations.find((d) => d.id === id);
+		if (!annotation) return;
+
+		const len = annotation.arrows.length;
+		annotation.arrows = annotation.arrows.filter((a) => a.side !== side);
+
+		// If we were hovering over an empty arrow zone, delete the annotation
+		if (len === annotation.arrows.length) {
+			deleteAnnotation(annotation.id);
+		}
+		saveConfig_debounced(annotations);
+	}
+
+	/**
+	 * If we press the delete key while hovering, delete the annotation or arrow
+	 */
+	function onkeydown(e) {
+		const hover = hovering.value;
+		if (!hover || isEditing.value === true) return;
+
+		if (e.key === 'Delete' || e.key === 'Backspace') {
+			if (hover.type === 'body') {
+				deleteAnnotation(hover.annotationId);
+			} else if (hover.type === 'arrow' && hover.side) {
+				deleteArrow(hover.annotationId, hover.side);
+			}
+			saveConfig_debounced(annotations);
+		}
+	}
+
+	/**
+	 * Save our modifier functions to the context
+	 */
+	setContext('modifyAnnotation', modifyAnnotation);
+	setContext('setArrow', setArrow);
+	setContext('modifyArrow', modifyArrow);
+</script>
+
+{#snippet defs()}
+	<ArrowheadMarker />
+{/snippet}
+
+<Svg {defs}>
+	<Arrows {annotations} />
+</Svg>
+
+<Html>
+	<div
+		onclick={debounce(onclick, 250, true)}
+		onkeydown={(e) => e.key === 'Enter' && onclick(e)}
+		role="button"
+		tabindex="0"
+		aria-label="Click to add annotation"
+		class="note-listener"
+	></div>
+
+	<div class="layercake-annotations">
+		{#each annotations as d (d.id)}
+			<AnnotationEditor {d} {containerClass} />
+		{/each}
+	</div>
+</Html>
+
+<svelte:window {onkeydown} />
+
+<style>
+	.note-listener {
+		width: 100%;
+		height: 100%;
+		cursor: copy;
+	}
+</style>

package/dist/Editor.svelte.d.ts

@@ -0,0 +1,19 @@
+export default Editor;
+export type Annotation = import("./types.js").Annotation;
+export type Arrow = import("./types.js").Arrow;
+export type HoverState = import("./types.js").HoverState;
+export type DragState = import("./types.js").DragState;
+export type SaveAnnotationConfigFn = import("./types.js").SaveAnnotationConfigFn;
+export type Ref<T> = import("./types.js").Ref<T>;
+type Editor = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+declare const Editor: import("svelte").Component<{
+    annotations?: Annotation[];
+    containerClass?: string;
+}, {}, "annotations">;
+type $$ComponentProps = {
+    annotations?: Annotation[];
+    containerClass?: string;
+};

package/dist/README.md

@@ -0,0 +1,200 @@
+# LayerCake Annotations - Internal Architecture
+
+This document describes the internal architecture of the annotation library for contributors and maintainers.
+
+## Overview
+
+LayerCake Annotations provides interactive text annotations with swoopy arrows for [LayerCake](https://layercake.graphics/) charts. It supports both linear and ordinal scales.
+
+## Component Structure
+
+```
+src/lib/
+├── Editor.svelte           # Interactive editing mode (exported as AnnotationsEditor)
+├── Static.svelte           # Read-only display mode (exported as AnnotationsStatic)
+├── components/
+│   ├── AnnotationEditor.svelte  # Individual annotation wrapper
+│   ├── ArrowZone.svelte         # Draggable arrow handles
+│   ├── Arrows.svelte            # SVG arrow rendering
+│   ├── Draggable.svelte         # Generic drag behavior
+│   ├── EditableText.svelte      # Editable text input
+│   ├── ResizeHandles.svelte     # Width resize handles
+│   ├── ArrowheadMarker.svelte   # SVG arrowhead definition
+│   └── AnnotationsData.svelte   # Static annotations renderer
+└── modules/
+    ├── coordinates.js      # Shared coordinate calculations
+    ├── arrowUtils.js       # SVG path generation
+    ├── createRef.svelte.js # Reactive state refs for context
+    ├── invertScale.js      # Scale inversion utilities
+    ├── ordinalInvert.js    # Ordinal scale inversion
+    ├── filterObject.js     # Object utilities
+    └── newAnnotation.js    # Annotation factory
+```
+
+## Data Model
+
+### Annotation Object
+
+```typescript
+{
+  id: number,              // Unique identifier
+  [xKey]: any,             // X data value (key from LayerCake config)
+  [yKey]: any,             // Y data value (key from LayerCake config)
+  dx: number,              // X offset: -100 to 100 (percentage of chart width)
+  dy: number,              // Y offset: -100 to 100 (percentage of chart height)
+  text: string,            // Annotation text (supports line breaks)
+  width?: string,          // Box width (e.g., "150px")
+  align?: string,          // Text alignment: 'left', 'center', or 'right'
+  arrows: Arrow[]          // Attached arrows
+}
+```
+
+**Note**: `dx` and `dy` are percentages (not decimals). Use `dx: 10` for 10% right, `dx: -5` for 5% left.
+
+### Arrow Object
+
+```typescript
+{
+  side: 'west' | 'east',   // Which side of annotation the arrow originates from
+  clockwise: boolean|null, // true = clockwise arc, false = counter-clockwise, null = straight
+  source: {
+    dx: number,            // Pixels from annotation edge (neg = further out)
+    dy: number             // Pixels from annotation vertical center
+  },
+  target: {
+    [xKey]: any,           // X data value (same accessor as LayerCake)
+    [yKey]: any,           // Y data value
+    dx?: number,           // 0-100: % offset within ordinal band (X)
+    dy?: number            // 0-100: % offset within ordinal band (Y)
+  }
+}
+```
+
+## Coordinate System
+
+The library uses multiple coordinate systems:
+
+### Annotation Position
+
+```
+Final position = scale(dataValue) + (dx/100 × chartDimension)
+```
+
+| Property | Unit | Range | Example |
+|----------|------|-------|---------|
+| `[xKey]` | Data value | Depends on data | `new Date('2024-01-15')` |
+| `[yKey]` | Data value | Depends on data | `42` |
+| `dx` | % of chart width | -100 to 100 | `5` = 5% right |
+| `dy` | % of chart height | -100 to 100 | `-10` = 10% up |
+
+### Arrow Source Position
+
+Pixels relative to annotation box edge:
+
+| Property | Unit | Meaning |
+|----------|------|---------|
+| `source.dx` | Pixels | Distance from annotation edge (west: left edge, east: right edge) |
+| `source.dy` | Pixels | Distance from annotation vertical center |
+
+### Arrow Target Position
+
+| Property | Unit | When used |
+|----------|------|-----------|
+| `[xKey]`, `[yKey]` | Data values | Always (same keys as LayerCake config) |
+| `dx`, `dy` | % within band (0-100) | Only for ordinal scales |
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| Double-click | Edit annotation text |
+| Enter | Save text and exit edit mode |
+| Shift+Enter | Insert line break while editing |
+| Escape | Cancel editing |
+| Cmd+click | Cycle text alignment: left → center → right |
+| Delete/Backspace | Delete hovered annotation or arrow |
+| Cmd+click on arrow | Toggle curve direction: clockwise → straight → counter-clockwise |
+
+## State Management
+
+State is shared via Svelte context using the `createRef` pattern:
+
+```javascript
+// In Editor.svelte
+const hovering = createRef(null);
+setContext('hovering', hovering);
+
+// In child components
+const hovering = getContext('hovering');
+hovering.value = { annotationId: 0, type: 'body' };
+```
+
+### Context Values
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `hovering` | `HoverState \| null` | Currently hovered element |
+| `moving` | `boolean` | Whether dragging is in progress |
+| `isEditing` | `boolean` | Whether text is being edited |
+| `previewArrow` | `DragState \| null` | Live arrow during drag |
+| `modifyAnnotation` | `function` | Update annotation props |
+| `setArrow` | `function` | Create/update arrow |
+| `modifyArrow` | `function` | Modify arrow properties |
+
+## Key Modules
+
+### coordinates.js
+
+Centralizes all coordinate calculations to prevent drift:
+
+```javascript
+import { 
+  getAnnotationBox,    // Get annotation position/size
+  getArrowSource,      // Get arrow source in pixels
+  getArrowTarget,      // Get arrow target in pixels
+  calculateSourceDx,   // Convert pixel to stored offset
+  DEFAULT_ANNOTATION_WIDTH
+} from './modules/coordinates.js';
+```
+
+### arrowUtils.js
+
+Generates SVG arc paths:
+
+```javascript
+import { createArrowPath } from './modules/arrowUtils.js';
+
+const path = createArrowPath(
+  { x: 100, y: 50 },   // source
+  { x: 200, y: 100 },  // target
+  true,                // clockwise
+  Math.PI / 2          // angle (optional)
+);
+```
+
+## Testing
+
+Tests use Playwright for visual regression testing:
+
+```bash
+pnpm test                              # Run tests
+pnpm exec playwright test --update-snapshots  # Update snapshots
+```
+
+Tests cover both linear scale (`/`) and ordinal scale (`/ordinal`) examples.
+
+## Common Tasks
+
+### Adding a new arrow property
+
+1. Update `Arrow` type in `types.d.ts`
+2. Update `setArrow` in `Editor.svelte` to handle the property
+3. Update `ArrowZone.svelte` to read/write the property
+4. Update `Arrows.svelte` if it affects rendering
+
+### Debugging coordinate issues
+
+1. Check that `coordinates.js` functions are being used consistently
+2. Verify the correct `scales` object is being passed
+3. For east arrows, remember `dx` is from the RIGHT edge
+

package/dist/Static.svelte

@@ -0,0 +1,24 @@
+<script>
+	/** @typedef {import('./types.js').Annotation} Annotation */
+
+	import { Svg, Html } from 'layercake';
+
+	import AnnotationsData from './components/AnnotationsData.svelte';
+	import ArrowheadMarker from './components/ArrowheadMarker.svelte';
+	import Arrows from './components/Arrows.svelte';
+
+	/** @type {{ annotations?: Annotation[] }} */
+	let { annotations = [] } = $props();
+</script>
+
+{#snippet defs()}
+		<ArrowheadMarker />
+{/snippet}
+
+<Svg {defs}>
+	<Arrows {annotations} />
+</Svg>
+
+<Html>
+	<AnnotationsData {annotations} />
+</Html>

package/dist/Static.svelte.d.ts

@@ -0,0 +1,12 @@
+export default Static;
+export type Annotation = import("./types.js").Annotation;
+type Static = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+declare const Static: import("svelte").Component<{
+    annotations?: Annotation[];
+}, {}, "">;
+type $$ComponentProps = {
+    annotations?: Annotation[];
+};