@fabrika/annotations 0.2.0

package/src/useRegionAnnotation.tsx

@@ -0,0 +1,190 @@
+import React, { useEffect, useRef, useState } from 'react'
+import { useAnnotations } from './AnnotationProvider'
+import { AnnotationCreatePopover } from './Popover'
+import {
+	applyRegionStyle,
+	createRegionOverlay,
+	describeRegion,
+	isDrawableRegion,
+	REGION_HOST_ATTR,
+	regionBetween,
+	type RegionPoint,
+	regionPointIn,
+	type RegionShape,
+	regionTarget,
+} from './regionTarget'
+import { generateAnnotationId } from './utils'
+
+interface UseRegionAnnotationOptions {
+	/** Container holding the image blocks a region can be drawn on. */
+	containerRef: React.RefObject<HTMLElement | null>
+	/** Re-registers the drawing listener when the canvas remounts. */
+	restoreKey: unknown
+	/** Shape a new region takes. */
+	shape?: RegionShape
+	/** Canvas file the created annotation belongs to. */
+	canvasFile?: string
+	/** Scroll container for popover positioning. */
+	scrollContainer?: HTMLElement | null
+}
+
+/** One region being drawn out, held outside React: the box follows the pointer
+ *  at pointer rate, which is no reason to re-render the canvas. */
+interface RegionDrag {
+	pointerId: number
+	host: HTMLElement
+	src: string
+	start: RegionPoint
+	shape: RegionShape
+	overlay: HTMLElement
+	id: string
+}
+
+/** A region drawn but not yet given a note. */
+interface PendingRegion {
+	overlay: HTMLElement
+	id: string
+	snippet: string
+	label: string
+}
+
+/**
+ * Drag on an image block to annotate one part of it.
+ *
+ * An image carries no text, so a plain drag over one is unambiguous and takes
+ * no modifier: the selection this would compete with cannot start there. It
+ * still has to stay off the two things that already live on an image block —
+ * the whole-image comment button and any region already drawn.
+ */
+export function useRegionAnnotation(options: UseRegionAnnotationOptions) {
+	const { containerRef, restoreKey, shape = 'rect', canvasFile, scrollContainer } = options
+	const { addAnnotationWithId } = useAnnotations()
+
+	const [pending, setPending] = useState<PendingRegion | null>(null)
+	const [isDrawing, setIsDrawing] = useState(false)
+
+	const addAnnotationRef = useRef(addAnnotationWithId)
+	addAnnotationRef.current = addAnnotationWithId
+	const canvasFileRef = useRef(canvasFile)
+	canvasFileRef.current = canvasFile
+	const shapeRef = useRef(shape)
+	shapeRef.current = shape
+
+	useEffect(() => {
+		const container = containerRef.current
+		if (!container) return
+
+		let drag: RegionDrag | null = null
+
+		/** Where the pointer is, on the region grid of `host`. */
+		function pointIn(host: HTMLElement, e: PointerEvent): RegionPoint | null {
+			const rect = host.getBoundingClientRect()
+			return regionPointIn(rect, e.clientX - rect.left, e.clientY - rect.top)
+		}
+
+		function endDrag() {
+			if (!drag) return
+			const { host, pointerId } = drag
+			if (host.hasPointerCapture(pointerId)) host.releasePointerCapture(pointerId)
+			host.removeEventListener('pointermove', onMove)
+			host.removeEventListener('pointerup', onUp)
+			host.removeEventListener('pointercancel', onCancel)
+			drag = null
+			setIsDrawing(false)
+		}
+
+		function onDown(e: PointerEvent) {
+			if (drag || e.button !== 0) return
+			const target = e.target
+			if (!(target instanceof Element)) return
+			// The comment button mints the whole-image annotation, and a region
+			// already drawn is its own click target; neither starts a new one.
+			if (target.closest('[data-block-comment-btn]')) return
+			if (target.closest('[data-annotation-id]')) return
+
+			const host = target.closest(`[${REGION_HOST_ATTR}]`)
+			if (!(host instanceof HTMLElement) || !container?.contains(host)) return
+			const src = host.closest("[data-md='image']")?.getAttribute('data-md-src')
+			if (!src) return
+			const start = pointIn(host, e)
+			if (!start) return
+
+			// Without this the browser starts its own image drag instead.
+			e.preventDefault()
+			host.setPointerCapture(e.pointerId)
+
+			const id = generateAnnotationId()
+			const overlay = createRegionOverlay({ ...start, w: 0, h: 0 }, shapeRef.current, id)
+			overlay.classList.add('ann-region-draft')
+			host.appendChild(overlay)
+
+			drag = { pointerId: e.pointerId, host, src, start, shape: shapeRef.current, overlay, id }
+			host.addEventListener('pointermove', onMove)
+			host.addEventListener('pointerup', onUp)
+			host.addEventListener('pointercancel', onCancel)
+			setIsDrawing(true)
+		}
+
+		function onMove(e: PointerEvent) {
+			if (!drag || drag.pointerId !== e.pointerId) return
+			const point = pointIn(drag.host, e)
+			if (!point) return
+			applyRegionStyle(drag.overlay, regionBetween(drag.start, point))
+		}
+
+		function onUp(e: PointerEvent) {
+			if (!drag || drag.pointerId !== e.pointerId) return
+			const { overlay, id, src, shape: drawnShape } = drag
+			const point = pointIn(drag.host, e) ?? drag.start
+			const box = regionBetween(drag.start, point)
+			endDrag()
+
+			if (!isDrawableRegion(box)) {
+				overlay.remove()
+				return
+			}
+			applyRegionStyle(overlay, box)
+			const locator = { src, shape: drawnShape, ...box }
+			setPending({ overlay, id, snippet: regionTarget.format(locator), label: describeRegion(locator) })
+		}
+
+		function onCancel(e: PointerEvent) {
+			if (!drag || drag.pointerId !== e.pointerId) return
+			drag.overlay.remove()
+			endDrag()
+		}
+
+		container.addEventListener('pointerdown', onDown)
+		return () => {
+			container.removeEventListener('pointerdown', onDown)
+			if (drag) {
+				drag.overlay.remove()
+				endDrag()
+			}
+		}
+	}, [restoreKey])
+
+	const popovers = pending
+		? (
+			<AnnotationCreatePopover
+				anchorEl={pending.overlay}
+				scrollContainer={scrollContainer}
+				snippet={pending.label}
+				truncateAt={80}
+				onAdd={(note, images) => {
+					// The overlay already carries the annotation's real id, so committing
+					// is only dropping the draft look — no redraw, no flicker.
+					pending.overlay.classList.remove('ann-region-draft')
+					addAnnotationRef.current(pending.id, pending.snippet, note, undefined, undefined, images, canvasFileRef.current)
+					setPending(null)
+				}}
+				onCancel={() => {
+					pending.overlay.remove()
+					setPending(null)
+				}}
+			/>
+		)
+		: null
+
+	return { popovers, isDrawing, isPopoverOpen: !!pending }
+}

package/src/useTextAnnotation.tsx

@@ -0,0 +1,208 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import { restoreAnnotationTargets } from './annotationDom'
+import type { Annotation, AnnotationContext } from './AnnotationProvider'
+import { useAnnotations } from './AnnotationProvider'
+import { rangeIndexText, renameMarkId, unwrapMarks, updateAllMarkStates, wrapRangeWithMark } from './highlightRange'
+import { AnnotationCreatePopover, AnnotationEditPopover } from './Popover'
+import { generateAnnotationId } from './utils'
+
+interface UseTextAnnotationOptions {
+	/** Ref to the container element where text can be selected and marks are placed */
+	containerRef: React.RefObject<HTMLElement | null>
+	/** Trigger for mark restoration — when this value changes, marks are restored */
+	restoreKey: unknown
+	/** Subset of annotations to restore in this container */
+	restoreAnnotations: Annotation[]
+	/** Build AnnotationContext from a selection Range */
+	extractContext: (range: Range) => AnnotationContext | undefined
+	/** Optional filePath to associate with created annotations */
+	filePath?: string
+	/** Optional canvasFile to associate with created annotations */
+	canvasFile?: string
+	/** Scroll container for popover positioning */
+	scrollContainer?: HTMLElement | null
+}
+
+export function useTextAnnotation(options: UseTextAnnotationOptions) {
+	const { containerRef, restoreKey, restoreAnnotations, extractContext, filePath, canvasFile, scrollContainer } = options
+	const {
+		annotations: allAnnotations,
+		addAnnotationWithId,
+		removeAnnotation,
+		updateAnnotation,
+		addAnnotationImage,
+		removeAnnotationImage,
+		activeAnnotationId,
+		setActiveAnnotationId,
+	} = useAnnotations()
+
+	const [editPopover, setEditPopover] = useState<{ anchorEl: HTMLElement; annId: string } | null>(null)
+	const [createPopover, setCreatePopover] = useState<{ anchorEl: HTMLElement; tempId: string; snippet: string; ctx?: AnnotationContext } | null>(null)
+
+	// Refs for stable handlers (registered with empty or minimal deps)
+	const extractContextRef = useRef(extractContext)
+	extractContextRef.current = extractContext
+	const filePathRef = useRef(filePath)
+	filePathRef.current = filePath
+	const canvasFileRef = useRef(canvasFile)
+	canvasFileRef.current = canvasFile
+	const addAnnotationRef = useRef(addAnnotationWithId)
+	addAnnotationRef.current = addAnnotationWithId
+	const activeAnnotationIdRef = useRef(activeAnnotationId)
+	activeAnnotationIdRef.current = activeAnnotationId
+	const setActiveAnnotationIdRef = useRef(setActiveAnnotationId)
+	setActiveAnnotationIdRef.current = setActiveAnnotationId
+
+	// Decoration restoration after content renders or annotations change. Not
+	// only marks: every locator strategy puts its own decoration back here, so a
+	// host that mounts this hook gets region overlays restored too.
+	const restoreAnnotationsLen = restoreAnnotations.length
+	useEffect(() => {
+		if (!containerRef.current) return
+		const timer = setTimeout(() => {
+			if (containerRef.current) {
+				restoreAnnotationTargets(containerRef.current, restoreAnnotations)
+			}
+		}, 50)
+		return () => clearTimeout(timer)
+	}, [restoreKey, restoreAnnotationsLen])
+
+	// Mark active state tracking
+	const prevActiveRef = useRef<string | null>(null)
+	useEffect(() => {
+		updateAllMarkStates(activeAnnotationId, prevActiveRef.current)
+		prevActiveRef.current = activeAnnotationId
+	}, [activeAnnotationId])
+
+	// Mark click/hover/out handlers on the container (uses refs to avoid re-registration on every hover)
+	useEffect(() => {
+		const container = containerRef.current
+		if (!container) return
+
+		const handleClick = (e: MouseEvent) => {
+			const mark = (e.target as HTMLElement).closest('[data-annotation-id]') as HTMLElement | null
+			if (!mark) return
+			e.stopPropagation()
+			const annId = mark.getAttribute('data-annotation-id')!
+			if (annId === activeAnnotationIdRef.current) {
+				setEditPopover({ anchorEl: mark, annId })
+			} else {
+				setActiveAnnotationIdRef.current(annId)
+			}
+		}
+
+		const handleMouseOver = (e: MouseEvent) => {
+			const mark = (e.target as HTMLElement).closest('[data-annotation-id]') as HTMLElement | null
+			if (mark) setActiveAnnotationIdRef.current(mark.getAttribute('data-annotation-id')!)
+		}
+
+		const handleMouseOut = (e: MouseEvent) => {
+			const mark = (e.target as HTMLElement).closest('[data-annotation-id]')
+			const related = (e.relatedTarget as HTMLElement | null)?.closest?.('[data-annotation-id]')
+			if (mark && !related && !document.getElementById('ann-inline-popover')) setActiveAnnotationIdRef.current(null)
+		}
+
+		container.addEventListener('click', handleClick)
+		container.addEventListener('mouseover', handleMouseOver)
+		container.addEventListener('mouseout', handleMouseOut)
+		return () => {
+			container.removeEventListener('click', handleClick)
+			container.removeEventListener('mouseover', handleMouseOver)
+			container.removeEventListener('mouseout', handleMouseOut)
+		}
+	}, [restoreKey])
+
+	// Document-level mouseup for text selection → mark → popover
+	useEffect(() => {
+		const handler = () => handleMouseUp()
+		document.addEventListener('mouseup', handler)
+		return () => document.removeEventListener('mouseup', handler)
+	}, [])
+
+	const handleMouseUp = useCallback(() => {
+		const sel = window.getSelection()
+		if (!sel || sel.isCollapsed || !sel.toString().trim()) return
+		if (!containerRef.current) return
+		const range = sel.getRangeAt(0)
+		if (!containerRef.current.contains(range.startContainer)) return
+		if ((range.startContainer.parentElement as HTMLElement)?.closest?.('[data-annotation-id]')) return
+		// Not sel.toString(): a selection reaching over an existing annotation
+		// carries text the index does not hold, and a snippet naming that text can
+		// never be restored.
+		const snippet = rangeIndexText(range).trim()
+		if (snippet.length < 2) return
+
+		// Extract context before wrapping disturbs the DOM
+		const ctx = extractContextRef.current(range)
+		const savedRange = range.cloneRange()
+		const tempId = `__pending_${Date.now()}`
+		try {
+			wrapRangeWithMark(savedRange, tempId)
+		} catch {}
+		window.getSelection()?.removeAllRanges()
+
+		const marks = document.querySelectorAll(`[data-annotation-id="${tempId}"]`)
+		const lastMark = marks[marks.length - 1] as HTMLElement | undefined
+		if (!lastMark) return
+
+		setCreatePopover({ anchorEl: lastMark, tempId, snippet, ctx })
+	}, [])
+
+	const openCreatePopover = useCallback((anchorEl: HTMLElement, tempId: string, snippet: string, ctx?: AnnotationContext) => {
+		setCreatePopover({ anchorEl, tempId, snippet, ctx })
+	}, [])
+
+	const popovers = (
+		<>
+			{editPopover && (() => {
+				const ann = allAnnotations.find((a) => a.id === editPopover.annId)
+				if (!ann) return null
+				return (
+					<AnnotationEditPopover
+						anchorEl={editPopover.anchorEl}
+						scrollContainer={scrollContainer}
+						initialNote={ann.note}
+						initialImages={ann.images}
+						onUpdate={(note, images) => {
+							updateAnnotation(editPopover.annId, note)
+							// Sync images
+							const current = ann.images || []
+							for (const img of images) {
+								if (!current.includes(img)) addAnnotationImage(editPopover.annId, img)
+							}
+							for (const img of current) {
+								if (!images.includes(img)) removeAnnotationImage(editPopover.annId, img)
+							}
+						}}
+						onDelete={() => {
+							removeAnnotation(editPopover.annId)
+							setActiveAnnotationId(null)
+						}}
+						onClose={() => setEditPopover(null)}
+					/>
+				)
+			})()}
+
+			{createPopover && (
+				<AnnotationCreatePopover
+					anchorEl={createPopover.anchorEl}
+					scrollContainer={scrollContainer}
+					snippet={createPopover.snippet}
+					truncateAt={80}
+					onAdd={(note, images) => {
+						const id = generateAnnotationId()
+						renameMarkId(createPopover.tempId, id)
+						addAnnotationRef.current(id, createPopover.snippet, note, filePathRef.current, createPopover.ctx, images, canvasFileRef.current)
+						setCreatePopover(null)
+					}}
+					onCancel={() => {
+						unwrapMarks(createPopover.tempId)
+						setCreatePopover(null)
+					}}
+				/>
+			)}
+		</>
+	)
+
+	return { popovers, openCreatePopover, isPopoverOpen: !!(editPopover || createPopover) }
+}

package/src/utils.ts

@@ -0,0 +1,33 @@
+/** Sentinel filePath for annotations on the agent response banner */
+export const RESPONSE_ANNOTATION_PATH = '__agent-response__'
+
+/**
+ * The file this annotation lives in, or undefined if it lives in no file.
+ * Response annotations ride in the same field under a sentinel, so a bare
+ * `if (ann.filePath)` opens a file tab for a path that is not one.
+ */
+export function fileAnnotationPath(ann: { filePath?: string }): string | undefined {
+	return ann.filePath && ann.filePath !== RESPONSE_ANNOTATION_PATH ? ann.filePath : undefined
+}
+
+/**
+ * Whether the attach-image affordances are drawn at all.
+ *
+ * The button, the paste handler and the drop zone all end in one POST to the
+ * host's upload endpoint, so a host without one gets none of the three instead
+ * of controls that fail silently.
+ */
+export function hostAcceptsUploads(host: { uploadUrl: (() => string) | null }): boolean {
+	return host.uploadUrl !== null
+}
+
+/** Generate a unique annotation ID */
+export function generateAnnotationId(): string {
+	return `ann-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`
+}
+
+/** Auto-resize a textarea to fit its content */
+export function autoResizeTextarea(el: HTMLTextAreaElement, minHeight?: number) {
+	el.style.height = 'auto'
+	el.style.height = (minHeight ? Math.max(minHeight, el.scrollHeight) : el.scrollHeight) + 'px'
+}