@fabrika/annotations 0.2.0

package/src/regionTarget.ts

@@ -0,0 +1,179 @@
+import type { AnnotationTarget } from './annotationTarget'
+
+/**
+ * A rectangle or ellipse drawn inside an image block, so a reader can point at
+ * one corner of a screenshot instead of the whole picture.
+ *
+ * Coordinates are normalized against the image box, which is a uniform scale of
+ * the image's natural size — that is what lets a region survive a resize, a
+ * zoom or a different screen. They are stored on a fixed integer grid rather
+ * than as floats: a float printed into the snippet and read back is not
+ * guaranteed to be the same float, and a locator that shifts by one ulp names
+ * a region nobody drew.
+ */
+
+/** The grid a region snaps to: hundredths of a percent of the image box. */
+export const REGION_UNITS = 10000
+
+/** Under this a drag is a stray click, not a region — 0.3% of the image. */
+const MIN_REGION_SIZE = 30
+
+export type RegionShape = 'rect' | 'ellipse'
+
+export interface RegionPoint {
+	x: number
+	y: number
+}
+
+/** Left, top, width and height, all in REGION_UNITS. */
+export interface RegionBox extends RegionPoint {
+	w: number
+	h: number
+}
+
+export interface RegionLocator extends RegionBox {
+	/** The image block the region sits in — the same `src` `[Image]` is keyed by. */
+	src: string
+	shape: RegionShape
+}
+
+/** Marks the element a region is measured against: the image's own box, not the
+ *  `<figure>`, which also holds the caption and would skew every percentage. */
+export const REGION_HOST_ATTR = 'data-annotation-image'
+
+// The coordinates are anchored at the end and strictly numeric, so the greedy
+// `src` group can hold anything at all — including a literal " @1,2,3,4" — and
+// still hand the real coordinates to the tail.
+const REGION_PATTERN = /^\[Region:(rect|ellipse)\] ([\s\S]+) @(0|[1-9]\d*),(0|[1-9]\d*),(0|[1-9]\d*),(0|[1-9]\d*)$/
+
+function readShape(value: string | undefined): RegionShape | null {
+	if (value === 'rect') return 'rect'
+	if (value === 'ellipse') return 'ellipse'
+	return null
+}
+
+/** A coordinate as `format` would have written it, or null. */
+function readUnit(value: string | undefined): number | null {
+	if (value === undefined) return null
+	const n = Number(value)
+	if (!Number.isInteger(n) || n < 0 || n > REGION_UNITS) return null
+	return n
+}
+
+export function clampUnit(value: number): number {
+	return Math.min(REGION_UNITS, Math.max(0, value))
+}
+
+/** Where a pointer landed inside a box, on the region grid. Null for a box with
+ *  no extent — happy-dom and a not-yet-laid-out image both report zero. */
+export function regionPointIn(box: { width: number; height: number }, offsetX: number, offsetY: number): RegionPoint | null {
+	if (!(box.width > 0) || !(box.height > 0)) return null
+	return {
+		x: clampUnit(Math.round((offsetX / box.width) * REGION_UNITS)),
+		y: clampUnit(Math.round((offsetY / box.height) * REGION_UNITS)),
+	}
+}
+
+/** The box two drag corners span, kept inside the image. */
+export function regionBetween(a: RegionPoint, b: RegionPoint): RegionBox {
+	const x = Math.min(a.x, b.x)
+	const y = Math.min(a.y, b.y)
+	return {
+		x,
+		y,
+		w: Math.min(REGION_UNITS - x, Math.abs(a.x - b.x)),
+		h: Math.min(REGION_UNITS - y, Math.abs(a.y - b.y)),
+	}
+}
+
+export function isDrawableRegion(box: RegionBox): boolean {
+	return box.w >= MIN_REGION_SIZE && box.h >= MIN_REGION_SIZE
+}
+
+/** CSS geometry for the overlay. REGION_UNITS is percent × 100, so every value
+ *  the grid holds divides out exactly. */
+export function regionStyle(box: RegionBox): { left: string; top: string; width: string; height: string } {
+	return {
+		left: `${box.x / 100}%`,
+		top: `${box.y / 100}%`,
+		width: `${box.w / 100}%`,
+		height: `${box.h / 100}%`,
+	}
+}
+
+function pct(units: number): string {
+	return `${(units / 100).toFixed(1).replace(/\.0$/, '')}%`
+}
+
+export function describeRegion(locator: RegionLocator): string {
+	const x = `${pct(locator.x)}-${pct(locator.x + locator.w)}`
+	const y = `${pct(locator.y)}-${pct(locator.y + locator.h)}`
+	return `[Region] ${locator.src} — ${locator.shape} x ${x}, y ${y} of the image`
+}
+
+/** The image box a region belongs to. Compared attribute by attribute rather
+ *  than through a selector, because an image src is a path and may carry any
+ *  character a selector would have to escape. */
+export function findRegionHost(src: string, root: ParentNode): HTMLElement | null {
+	for (const figure of root.querySelectorAll("[data-md='image']")) {
+		if (!(figure instanceof HTMLElement)) continue
+		if (figure.getAttribute('data-md-src') !== src) continue
+		const host = figure.querySelector(`[${REGION_HOST_ATTR}]`)
+		if (host instanceof HTMLElement) return host
+	}
+	return null
+}
+
+export function applyRegionStyle(el: HTMLElement, box: RegionBox): void {
+	const style = regionStyle(box)
+	el.style.left = style.left
+	el.style.top = style.top
+	el.style.width = style.width
+	el.style.height = style.height
+}
+
+/** The overlay box for one region. It carries `data-annotation-id`, so the
+ *  hover, active-state and delete plumbing that already drives inline marks
+ *  drives these too. */
+export function createRegionOverlay(box: RegionBox, shape: RegionShape, annotationId: string): HTMLElement {
+	const el = document.createElement('div')
+	el.className = 'ann-region'
+	el.setAttribute('data-annotation-id', annotationId)
+	el.setAttribute('data-annotation-region', shape)
+	applyRegionStyle(el, box)
+	return el
+}
+
+export const regionTarget: AnnotationTarget<RegionLocator> = {
+	kind: 'region',
+
+	parse: (snippet) => {
+		const match = REGION_PATTERN.exec(snippet)
+		if (!match) return null
+		const shape = readShape(match[1])
+		const src = match[2]
+		const x = readUnit(match[3])
+		const y = readUnit(match[4])
+		const w = readUnit(match[5])
+		const h = readUnit(match[6])
+		if (shape === null || src === undefined) return null
+		if (x === null || y === null || w === null || h === null) return null
+		if (w < 1 || h < 1) return null
+		return { src, shape, x, y, w, h }
+	},
+
+	format: (locator) => `[Region:${locator.shape}] ${locator.src} @${locator.x},${locator.y},${locator.w},${locator.h}`,
+
+	// The overlay is found by annotation id like any other decoration; this is
+	// the fallback for before it is drawn, and it lands on the right image.
+	find: (locator, root) => findRegionHost(locator.src, root),
+
+	restore: (locator, root, ann) => {
+		if (root.querySelector(`[data-annotation-id="${ann.id}"]`)) return
+		const host = findRegionHost(locator.src, root)
+		if (!host) return
+		host.appendChild(createRegionOverlay(locator, locator.shape, ann.id))
+	},
+
+	describe: describeRegion,
+}

package/src/runtime.ts

@@ -0,0 +1,86 @@
+import { createContext, useContext } from 'react'
+
+export interface AnnotationContext {
+	before: string
+	after: string
+	hierarchy: string[]
+	lineStart?: number
+	lineEnd?: number
+}
+
+export interface AnnotationAuthor {
+	id: string
+	name: string
+}
+
+export interface AnnotationAttachment {
+	url: string
+	mime?: string
+}
+
+export interface Annotation {
+	id: string
+	snippet: string
+	note: string
+	createdAt: string
+	filePath?: string
+	canvasFile?: string
+	context?: AnnotationContext
+	images?: string[]
+	attachments?: AnnotationAttachment[]
+	source?: 'local' | 'remote'
+	author?: AnnotationAuthor
+}
+
+export interface AnnotationState {
+	annotations: Annotation[]
+	generalNote: string
+}
+
+export interface AnnotationContextValue extends AnnotationState {
+	addAnnotation: (snippet: string, note: string, filePath?: string) => void
+	addAnnotationWithId: (
+		id: string,
+		snippet: string,
+		note: string,
+		filePath?: string,
+		context?: AnnotationContext,
+		images?: string[],
+		canvasFile?: string,
+	) => void
+	updateAnnotation: (id: string, note: string) => void
+	removeAnnotation: (id: string) => void
+	addAnnotationImage: (id: string, imagePath: string) => void
+	removeAnnotationImage: (id: string, imagePath: string) => void
+	setGeneralNote: (text: string) => void
+	clearAll: () => void
+	activeAnnotationId: string | null
+	setActiveAnnotationId: (id: string | null) => void
+	isReadOnly: boolean
+}
+
+export interface AnnotationHost {
+	sessionId: string
+	isShared: boolean
+	fsAvailable: boolean
+	uploadUrl: (() => string) | null
+}
+
+export const AnnotationCtx = createContext<AnnotationContextValue | null>(null)
+export const SessionContext = createContext<string>('')
+export const AnnotationHostContext = createContext<AnnotationHost>({
+	sessionId: '',
+	isShared: false,
+	fsAvailable: false,
+	uploadUrl: null,
+})
+
+export function useAnnotations(): AnnotationContextValue {
+	const value = useContext(AnnotationCtx)
+	if (!value) throw new Error('useAnnotations requires an AnnotationProvider')
+	return value
+}
+
+export function useAnnotationHost(): AnnotationHost {
+	return useContext(AnnotationHostContext)
+}

package/src/styles.css

@@ -0,0 +1,70 @@
+@source "./**/*.{tsx,ts,jsx,js}";
+
+mark[data-annotation-id] {
+  background: var(--color-highlight-annotation);
+  border-bottom: 1.5px solid var(--color-highlight-bg);
+  border-radius: 2px;
+  cursor: pointer;
+  transition: background 150ms ease, box-shadow 150ms ease;
+  color: inherit;
+  padding: 1px 0;
+}
+
+mark[data-annotation-id].mark-active {
+  background: var(--color-highlight-active);
+  border-bottom: 2px solid var(--color-highlight-border);
+  box-shadow: 0 0 0 1px var(--color-highlight-border);
+}
+
+@keyframes ann-flash {
+  0%, 100% { background: var(--color-highlight-annotation); }
+  25%, 75% { background: var(--color-highlight-active); }
+}
+
+.ann-flash {
+  animation: ann-flash 0.6s ease 2;
+}
+
+[data-annotation-image] {
+  position: relative;
+  cursor: crosshair;
+  touch-action: none;
+}
+
+.ann-region {
+  position: absolute;
+  background: var(--color-highlight-annotation);
+  border: 2px solid var(--color-highlight-bg);
+  border-radius: 2px;
+  cursor: pointer;
+  transition: background 150ms ease, box-shadow 150ms ease;
+}
+
+.ann-region[data-annotation-region="ellipse"] {
+  border-radius: 50%;
+}
+
+.ann-region.mark-active {
+  background: var(--color-highlight-active);
+  border-color: var(--color-highlight-border);
+  box-shadow: 0 0 0 1px var(--color-highlight-border);
+}
+
+.ann-region-draft {
+  pointer-events: none;
+  border-style: dashed;
+  border-color: var(--color-highlight-border);
+}
+
+.annotation-highlight {
+  background: var(--color-highlight-bg);
+  border-bottom: 2px solid var(--color-highlight-border);
+  border-radius: 2px;
+  cursor: pointer;
+  transition: background 150ms ease;
+}
+
+.annotation-highlight:hover,
+.annotation-highlight.active {
+  background: var(--color-highlight-active);
+}

package/src/testing/dom.ts

@@ -0,0 +1,74 @@
+/**
+ * DOM harness for the client tests.
+ *
+ * Import this **before** the module under test. ESM evaluates imports in order,
+ * so putting it first is what guarantees the globals exist by the time anything
+ * that reads `document` is evaluated.
+ *
+ * happy-dom is not a browser: it runs no layout. Everything geometric —
+ * `getBoundingClientRect`, `scrollHeight`, `offsetWidth` — reads zero unless the
+ * test stubs it, and `scrollIntoView` and CSS animations do nothing. Assert on
+ * structure and on the values a function computes, never on real measurements.
+ */
+import { GlobalRegistrator } from '@happy-dom/global-registrator'
+
+// Bun runs every test file in one process, so the second file to import this
+// must not register over the first.
+if (!globalThis.document) {
+	// happy-dom replaces the whole fetch stack with a Window implementation over
+	// node:http. That is not what this harness is for, and because every test
+	// file shares one process it reaches code that has nothing to do with the
+	// DOM — the daemon lifecycle probes `/health` through the global `fetch` and
+	// fails on responses Bun parses fine. Which tests broke depended on file
+	// order, so it passed locally and failed in CI. Keep Bun's stack.
+	const runtimeFetch = globalThis.fetch
+	const runtimeResponse = globalThis.Response
+	const runtimeRequest = globalThis.Request
+	const runtimeHeaders = globalThis.Headers
+
+	GlobalRegistrator.register()
+
+	globalThis.fetch = runtimeFetch
+	globalThis.Response = runtimeResponse
+	globalThis.Request = runtimeRequest
+	globalThis.Headers = runtimeHeaders
+}
+
+/**
+ * Replace the document body with `html` inside a fresh container and return it.
+ * Call it at the start of each test — the document is shared across every test
+ * in the process, so whatever the previous one left behind is still there.
+ */
+export function mountContainer(html: string): HTMLElement {
+	document.body.innerHTML = `<div data-testid="container">${html}</div>`
+	const container = document.body.firstElementChild
+	if (!(container instanceof HTMLElement)) throw new Error('container did not mount')
+	return container
+}
+
+/**
+ * A Range over the first occurrence of `text` within a single text node of
+ * `root`, which is how a reader's selection arrives in the annotation code.
+ * Throws rather than returning null so a typo in the fixture fails the test at
+ * its cause instead of somewhere downstream.
+ */
+export function selectText(root: HTMLElement, text: string): Range {
+	const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT)
+	let node: Node | null
+	while ((node = walker.nextNode())) {
+		const content = node.textContent ?? ''
+		const index = content.indexOf(text)
+		if (index === -1) continue
+		const range = document.createRange()
+		range.setStart(node, index)
+		range.setEnd(node, index + text.length)
+		return range
+	}
+	throw new Error(`no text node in the fixture contains ${JSON.stringify(text)}`)
+}
+
+/** Ids of the marks currently wrapping annotated text, in document order. */
+export function markIds(root: HTMLElement): string[] {
+	return [...root.querySelectorAll('[data-annotation-id]')]
+		.map((el) => el.getAttribute('data-annotation-id') ?? '')
+}

package/src/textTarget.ts

@@ -0,0 +1,31 @@
+import type { AnnotationTarget } from './annotationTarget'
+import { restoreMarks } from './highlightRange'
+
+/** A run of text, identified by the text itself. */
+export interface TextLocator {
+	text: string
+}
+
+/**
+ * Selected text, wrapped in inline `<mark>` elements.
+ *
+ * The fallback target: any snippet at all is text, so this one claims
+ * everything the others turned down and must stay last in the registry.
+ */
+export const textTarget: AnnotationTarget<TextLocator> = {
+	kind: 'text',
+
+	parse: (snippet) => (snippet ? { text: snippet } : null),
+
+	format: (locator) => locator.text,
+
+	// A run of text has no element of its own until a mark wraps it, and the mark
+	// is found by annotation id, not by the text. Guessing the element back from
+	// page text would resolve an annotation onto whatever happens to read the
+	// same today, so a missing mark stays a miss.
+	find: () => null,
+
+	restore: (_locator, root, ann) => {
+		restoreMarks(root, [ann])
+	},
+}

package/src/useAnnotationState.ts

@@ -0,0 +1,114 @@
+import { useCallback, useMemo, useState } from 'react'
+import type { Dispatch, SetStateAction } from 'react'
+import type { Annotation, AnnotationContext, AnnotationContextValue } from './runtime'
+import { generateAnnotationId } from './utils'
+
+interface AnnotationStateOptions {
+	annotations: Annotation[]
+	setAnnotations: Dispatch<SetStateAction<Annotation[]>>
+	generalNote: string
+	setGeneralNote: (note: string) => void
+	remoteAnnotations?: Annotation[]
+	isReadOnly: boolean
+	onClear?: () => void
+}
+
+function removeMarks(id?: string) {
+	const selector = id ? `[data-annotation-id="${CSS.escape(id)}"]` : '[data-annotation-id]'
+	for (const mark of document.querySelectorAll(selector)) {
+		if (mark.tagName === 'MARK') {
+			const parent = mark.parentNode
+			mark.replaceWith(document.createTextNode(mark.textContent || ''))
+			parent?.normalize()
+		} else {
+			mark.remove()
+		}
+	}
+}
+
+export function useAnnotationState({
+	annotations: localAnnotations,
+	setAnnotations,
+	generalNote,
+	setGeneralNote,
+	remoteAnnotations,
+	isReadOnly,
+	onClear,
+}: AnnotationStateOptions): AnnotationContextValue {
+	const [activeAnnotationId, setActiveAnnotationId] = useState<string | null>(null)
+	const annotations = useMemo<Annotation[]>(() => {
+		if (!remoteAnnotations?.length) return localAnnotations
+		const ids = new Set(localAnnotations.map((annotation) => annotation.id))
+		const remote = remoteAnnotations.filter((annotation) => !ids.has(annotation.id))
+		return [...localAnnotations, ...remote.map((annotation): Annotation => ({ ...annotation, source: 'remote' }))]
+	}, [localAnnotations, remoteAnnotations])
+
+	const addAnnotationWithId = useCallback(
+		(id: string, snippet: string, note: string, filePath?: string, context?: AnnotationContext, images?: string[], canvasFile?: string) => {
+			setAnnotations((prev) => [...prev, {
+				id,
+				snippet,
+				note,
+				createdAt: new Date().toISOString(),
+				filePath,
+				context,
+				...(images?.length ? { images } : {}),
+				...(canvasFile ? { canvasFile } : {}),
+			}])
+		},
+		[setAnnotations],
+	)
+	const addAnnotation = useCallback((snippet: string, note: string, filePath?: string) => {
+		addAnnotationWithId(generateAnnotationId(), snippet, note, filePath)
+	}, [addAnnotationWithId])
+	const updateAnnotation = useCallback((id: string, note: string) => {
+		setAnnotations((prev) => prev.map((annotation) => annotation.id === id ? { ...annotation, note } : annotation))
+	}, [setAnnotations])
+	const removeAnnotation = useCallback((id: string) => {
+		if (!localAnnotations.some((annotation) => annotation.id === id)) return
+		removeMarks(id)
+		setAnnotations((prev) => prev.filter((annotation) => annotation.id !== id))
+		setActiveAnnotationId((prev) => prev === id ? null : prev)
+	}, [localAnnotations, setAnnotations])
+	const addAnnotationImage = useCallback((id: string, imagePath: string) => {
+		setAnnotations((prev) =>
+			prev.map((annotation) =>
+				annotation.id === id
+					? { ...annotation, images: [...(annotation.images || []), imagePath] }
+					: annotation
+			)
+		)
+	}, [setAnnotations])
+	const removeAnnotationImage = useCallback((id: string, imagePath: string) => {
+		setAnnotations((prev) =>
+			prev.map((annotation) =>
+				annotation.id === id
+					? { ...annotation, images: (annotation.images || []).filter((image) => image !== imagePath) }
+					: annotation
+			)
+		)
+	}, [setAnnotations])
+	const clearAll = useCallback(() => {
+		removeMarks()
+		setAnnotations([])
+		setGeneralNote('')
+		setActiveAnnotationId(null)
+		onClear?.()
+	}, [setAnnotations, setGeneralNote, onClear])
+
+	return {
+		annotations,
+		generalNote,
+		setGeneralNote,
+		activeAnnotationId,
+		setActiveAnnotationId,
+		addAnnotation,
+		addAnnotationWithId,
+		updateAnnotation,
+		removeAnnotation,
+		addAnnotationImage,
+		removeAnnotationImage,
+		clearAll,
+		isReadOnly,
+	}
+}