Annotation Editor

interface AnnotationStorageAdapter<TBody = W3CAnnotationBody> {
    readonly id: string;
    readonly name: string;

    /**
     * Return every annotation stored for this manifest+canvas ([] when none).
     * `AdapterLoadResult` is `W3CAnnotation` plus the optional skeleton
     * markers described below.
     */
    load(manifestId: string, canvasId: string): Promise<AdapterLoadResult<TBody>[]>;

    /**
     * Persist a new annotation. Return the canonical annotation (or just its id
     * string) if your server assigns the id — the plugin reconciles it. Return
     * nothing to keep the id the plugin sent.
     */
    create(
        manifestId: string,
        canvasId: string,
        annotation: W3CAnnotation<TBody>,
    ): Promise<W3CAnnotation<TBody> | string | void>;

    /** Persist an update. Return the (possibly normalized) annotation to adopt it. */
    update(
        manifestId: string,
        canvasId: string,
        annotation: W3CAnnotation<TBody>,
    ): Promise<W3CAnnotation<TBody> | void>;

    /** Remove an annotation by id. */
    delete(manifestId: string, canvasId: string, annotationId: string): Promise<void>;

    /** Optional: fetch one annotation's full body on demand (see below). */
    hydrate?(
        manifestId: string,
        canvasId: string,
        annotationId: string,
    ): Promise<AdapterLoadResult<TBody> | null>;

    /** Optional: release resources when the plugin is destroyed. */
    destroy?(): void;
}

/**
 * What `load()`/`hydrate()` may return: a stored annotation plus the internal
 * skeleton markers the plugin reads once and strips before anything enters
 * the cache. These markers never round-trip, so they live here rather than on
 * `W3CAnnotation` itself. Both types are exported from the package.
 */
type AdapterLoadResult<TBody = W3CAnnotationBody> = W3CAnnotation<TBody> & {
    __fullBodyLoaded?: boolean;
    __bodyPreview?: string | null;
};

import {
    createAnnotationEditorPlugin,
    type AnnotationStorageAdapter,
    type W3CAnnotation,
} from '@triiiceratops/plugin-annotation-editor';

class AnnotationServerAdapter implements AnnotationStorageAdapter {
    readonly id = 'annotation-server';
    readonly name = 'Annotation Server';

    constructor(private baseUrl: string) {}

    /** One container per manifest+canvas. */
    private container(manifestId: string, canvasId: string): string {
        const key = encodeURIComponent(`${manifestId}::${canvasId}`);
        return `${this.baseUrl}/containers/${key}/`;
    }

    async load(manifestId: string, canvasId: string): Promise<W3CAnnotation[]> {
        const res = await fetch(this.container(manifestId, canvasId), {
            headers: { Accept: 'application/ld+json' },
        });
        // An empty container is normal — return [] rather than throwing.
        if (res.status === 404) return [];
        if (!res.ok) throw new Error(`load failed: ${res.status}`);
        const page = await res.json();
        return page.items ?? [];
    }

    async create(
        manifestId: string,
        canvasId: string,
        annotation: W3CAnnotation,
    ): Promise<W3CAnnotation> {
        const res = await fetch(this.container(manifestId, canvasId), {
            method: 'POST',
            headers: { 'Content-Type': 'application/ld+json' },
            body: JSON.stringify(annotation),
        });
        if (!res.ok) throw new Error(`create failed: ${res.status}`);
        // Prefer the server's returned representation; fall back to the id it
        // minted in the Location header. Returning the canonical annotation lets
        // the plugin reconcile the id everywhere it is displayed and edited.
        const location = res.headers.get('Location');
        const created = await res.json().catch(() => null);
        if (created?.id) return created;
        if (location) return { ...annotation, id: location };
        return created ?? annotation;
    }

    async update(
        manifestId: string,
        canvasId: string,
        annotation: W3CAnnotation,
    ): Promise<W3CAnnotation> {
        const res = await fetch(annotation.id, {
            method: 'PUT',
            headers: { 'Content-Type': 'application/ld+json' },
            body: JSON.stringify(annotation),
        });
        if (!res.ok) throw new Error(`update failed: ${res.status}`);
        return (await res.json().catch(() => null)) ?? annotation;
    }

    async delete(
        _manifestId: string,
        _canvasId: string,
        annotationId: string,
    ): Promise<void> {
        const res = await fetch(annotationId, { method: 'DELETE' });
        if (!res.ok && res.status !== 404) {
            throw new Error(`delete failed: ${res.status}`);
        }
    }
}

const plugin = createAnnotationEditorPlugin({
    adapter: new AnnotationServerAdapter('https://annotations.example.org'),
});

// MyAdapter.contract.test.ts
import { runAdapterContractTests } from '@triiiceratops/plugin-annotation-editor/testing';
import { MyAdapter } from './MyAdapter';

runAdapterContractTests(() => new MyAdapter(), {
    supportsIdReconciliation: true, // create returns a server-minted id
    supportsHydrate: true, // hydrate() is implemented
});

// example-ignore
import {
    createAnnotationEditorPlugin,
    type AnnotationEditorExtension,
} from '@triiiceratops/plugin-annotation-editor';

const extension: AnnotationEditorExtension<{ selectedText: string | null }> = {
    getContext: () => ({ selectedText: window.appSelection ?? null }),
    canCreate: ({ hostContext }) => !!hostContext?.selectedText,
    getCreateDisabledReason: ({ hostContext }) =>
        hostContext?.selectedText
            ? null
            : 'Select text before creating an annotation.',
    prepareDraft: (annotation, { hostContext }) => ({
        ...annotation,
        body: hostContext?.selectedText
            ? [
                  {
                      type: 'TextualBody',
                      purpose: 'commenting',
                      value: hostContext.selectedText,
                  },
              ]
            : [],
    }),
    beforeSave: async (annotation, context) => annotation,
    onSelectionChange: (annotation, context) => {},
};

const plugin = createAnnotationEditorPlugin({ extension });

const extension: AnnotationEditorExtension<{ selectedText: string | null }> = {
    getContext: () => ({ selectedText: window.appSelection ?? null }),
    canCreate: ({ hostContext }) => !!hostContext?.selectedText,
    subscribe: (invalidate) => {
        // Re-evaluate the gate whenever the host selection changes.
        window.addEventListener('selectionchange', invalidate);
        return () => window.removeEventListener('selectionchange', invalidate);
    },
};

const plugin = createAnnotationEditorPlugin({
    pointStyle: { radius: 6, fill: '#e5484d', stroke: '#ffffff', strokeWidth: 2 },
});

interface AnnotationBodyEditorApi {
    annotation: W3CAnnotation; // full (hydrated) annotation, canvas space
    bodies: unknown[]; // current bodies, untyped — you own the shape
    context: AnnotationEditorRuntimeContext;
    isHydrating: boolean;
    save: (bodies: unknown[] | unknown) => Promise<void>; // persists via the store
    cancel: () => void;
    requestDelete: () => void;
}

type AnnotationBodyEditor =
    | { component: Component<{ api: AnnotationBodyEditorApi }> } // Svelte hosts
    | { render: (container: HTMLElement, api: AnnotationBodyEditorApi) => (() => void) | void };

const annotationPlugin = createAnnotationEditorPlugin({
    adapter: new LocalStorageAdapter(),
    target: 'flyout', // a compact button + popover instead of a docked panel
    tools: ['point'],
    defaultTool: 'point',
    ui: {
        showModeToggle: false, // no Edit/Create switch
        startInCreateMode: true, // clicking the canvas drops a point immediately
        showUndoRedo: false,
        allowMultipleBodies: false,
    },
    bodyEditor: {
        render(container, api) {
            const current = (api.bodies[0] as any) ?? { label: '', confidence: 'medium' };
            container.innerHTML = `
                <form>
                    <label>Label <input name="label" /></label>
                    <label>Confidence
                        <select name="confidence">
                            <option value="low">low</option>
                            <option value="medium">medium</option>
                            <option value="high">high</option>
                        </select>
                    </label>
                    <button type="submit">Save</button>
                </form>`;
            const form = container.querySelector('form')!;
            (form.elements as any).label.value = current.label ?? '';
            (form.elements as any).confidence.value = current.confidence ?? 'medium';
            const submit = (e: Event) => {
                e.preventDefault();
                const data = new FormData(form);
                api.save({
                    type: 'TriiiceratopsDemoBody',
                    label: data.get('label'),
                    confidence: data.get('confidence'),
                });
            };
            form.addEventListener('submit', submit);
            return () => form.removeEventListener('submit', submit);
        },
    },
});