@fabrika/annotations 0.9.0-dev.1 → 0.9.0-dev.2

package/types/src/testing/dom.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function mountContainer(html: string): HTMLElement;
+/**
+ * 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 declare function selectText(root: HTMLElement, text: string): Range;
+/** Ids of the marks currently wrapping annotated text, in document order. */
+export declare function markIds(root: HTMLElement): string[];

package/types/src/textTarget.d.ts

@@ -0,0 +1,12 @@
+import type { AnnotationTarget } from './annotationTarget';
+/** 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 declare const textTarget: AnnotationTarget<TextLocator>;

package/types/src/useAnnotationState.d.ts

@@ -0,0 +1,13 @@
+import type { Dispatch, SetStateAction } from 'react';
+import type { Annotation, AnnotationContextValue } from './runtime';
+interface AnnotationStateOptions {
+    annotations: Annotation[];
+    setAnnotations: Dispatch<SetStateAction<Annotation[]>>;
+    generalNote: string;
+    setGeneralNote: (note: string) => void;
+    remoteAnnotations?: Annotation[];
+    isReadOnly: boolean;
+    onClear?: () => void;
+}
+export declare function useAnnotationState({ annotations: localAnnotations, setAnnotations, generalNote, setGeneralNote, remoteAnnotations, isReadOnly, onClear, }: AnnotationStateOptions): AnnotationContextValue;
+export {};

package/types/src/useRegionAnnotation.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+import { type RegionShape } from './regionTarget';
+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;
+}
+/**
+ * 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 declare function useRegionAnnotation(options: UseRegionAnnotationOptions): {
+    popovers: React.JSX.Element | null;
+    isDrawing: boolean;
+    isPopoverOpen: boolean;
+};
+export {};

package/types/src/useTextAnnotation.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+import type { Annotation, AnnotationContext } from './AnnotationProvider';
+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 declare function useTextAnnotation(options: UseTextAnnotationOptions): {
+    popovers: React.JSX.Element;
+    openCreatePopover: (anchorEl: HTMLElement, tempId: string, snippet: string, ctx?: AnnotationContext) => void;
+    isPopoverOpen: boolean;
+};
+export {};

package/types/src/utils.d.ts

@@ -0,0 +1,24 @@
+/** Sentinel filePath for annotations on the agent response banner */
+export declare 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 declare function fileAnnotationPath(ann: {
+    filePath?: string;
+}): string | 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 declare function hostAcceptsUploads(host: {
+    uploadUrl: (() => string) | null;
+}): boolean;
+/** Generate a unique annotation ID */
+export declare function generateAnnotationId(): string;
+/** Auto-resize a textarea to fit its content */
+export declare function autoResizeTextarea(el: HTMLTextAreaElement, minHeight?: number): void;