@xats-org/types/dist/annotations.d.ts

Shared TypeScript types for xats

/**
 * xats v0.5.0 Annotation System Types
 *
 * TypeScript type definitions for the peer review and annotation system
 * introduced in xats schema version 0.5.0
 */
import type { XatsObject } from './common.js';
import type { SemanticText } from './document.js';
/**
 * Text range specification for precise targeting
 */
export interface TextRange {
    /** Character offset from beginning of target text where range starts */
    startOffset: number;
    /** Character offset from beginning of target text where range ends */
    endOffset: number;
    /** The actual text content being annotated */
    textContent: string;
    /** Optional XPath expression for targeting specific elements */
    xpath?: string;
    /** Optional CSS-style selector for web-based targeting */
    selector?: string;
}
/**
 * Formal review decision structure
 */
export interface ReviewDecision {
    /** The formal review decision outcome */
    decision: 'approve' | 'reject' | 'request_changes' | 'conditional_accept';
    /** Reviewer confidence level (1-5 scale, 5 = highest confidence) */
    confidence: number;
    /** Specific review criteria that influenced this decision */
    criteria?: string[];
    /** Detailed explanation for the review decision */
    justification: SemanticText;
    /** Specific actions recommended to address review findings */
    recommendedActions?: RecommendedAction[];
}
/**
 * Recommended action for addressing review findings
 */
export interface RecommendedAction {
    /** Type of action recommended */
    action: string;
    /** Description of the action */
    description: SemanticText;
    /** Priority level for this action */
    priority: 'low' | 'medium' | 'high' | 'critical';
}
/**
 * Annotation status values
 */
export type AnnotationStatus = 'open' | 'resolved' | 'rejected' | 'deferred';
/**
 * Annotation priority levels
 */
export type AnnotationPriority = 'low' | 'medium' | 'high' | 'critical';
/**
 * Standard xats annotation type URIs
 */
export declare const ANNOTATION_TYPE_URIS: {
    /** Proposed change to content */
    readonly SUGGESTION: "https://xats.org/vocabularies/annotations/suggestion";
    /** Need for more information */
    readonly CLARIFICATION_REQUEST: "https://xats.org/vocabularies/annotations/clarification_request";
    /** Small fix required */
    readonly MINOR_REVISION_NEEDED: "https://xats.org/vocabularies/annotations/minor_revision_needed";
    /** Significant change required */
    readonly MAJOR_REVISION_NEEDED: "https://xats.org/vocabularies/annotations/major_revision_needed";
    /** Content approved */
    readonly APPROVAL: "https://xats.org/vocabularies/annotations/approval";
    /** Content rejected */
    readonly REJECTION: "https://xats.org/vocabularies/annotations/rejection";
};
/**
 * Union type for standard annotation type URIs
 */
export type StandardAnnotationType = (typeof ANNOTATION_TYPE_URIS)[keyof typeof ANNOTATION_TYPE_URIS];
/**
 * Core annotation interface extending XatsObject
 */
export interface Annotation extends XatsObject {
    /** Required unique identifier */
    id: string;
    /** Required language code */
    language: string;
    /** URI identifying the type of annotation */
    annotationType: string;
    /** The ID of the XatsObject this annotation references */
    targetObjectId: string;
    /** Specific text range within the target object */
    targetRange?: TextRange;
    /** Current status of the annotation */
    status: AnnotationStatus;
    /** Priority level for addressing this annotation */
    priority: AnnotationPriority;
    /** Identifier for the person assigned to address this annotation */
    assignee?: string;
    /** Identifier for the person who created this annotation */
    reviewer: string;
    /** Identifier for grouping related annotations into discussion threads */
    threadId?: string;
    /** ID of parent annotation for hierarchical discussion threads */
    parentAnnotationId?: string;
    /** The annotation content */
    content: SemanticText;
    /** Proposed replacement content for suggestion-type annotations */
    suggestedChange?: SemanticText;
    /** Formal review decision with criteria and justification */
    reviewDecision?: ReviewDecision;
    /** ISO 8601 timestamp when annotation was created */
    createdAt: string;
    /** ISO 8601 timestamp when annotation was last modified */
    updatedAt?: string;
    /** ISO 8601 timestamp when annotation was resolved */
    resolvedAt?: string;
    /** Nested annotations for hierarchical structures */
    annotations?: Annotation[];
}
/**
 * Parameters for creating a new annotation
 */
export interface CreateAnnotationParams {
    annotationType: string;
    targetObjectId: string;
    content: SemanticText;
    reviewer: string;
    targetRange?: TextRange;
    priority?: AnnotationPriority;
    assignee?: string;
    threadId?: string;
    parentAnnotationId?: string;
    suggestedChange?: SemanticText;
    reviewDecision?: ReviewDecision;
    language?: string;
}
/**
 * Filters for annotation queries
 */
export interface AnnotationFilters {
    status?: AnnotationStatus;
    priority?: AnnotationPriority;
    annotationType?: string;
    reviewer?: string;
    assignee?: string;
    targetObjectId?: string;
    threadId?: string;
}
/**
 * Review progress metrics
 */
export interface ReviewProgress {
    /** Total number of annotations */
    total: number;
    /** Number of open annotations */
    open: number;
    /** Number of resolved annotations */
    resolved: number;
    /** Number of rejected annotations */
    rejected: number;
    /** Number of deferred annotations */
    deferred: number;
    /** Completion percentage */
    completionRate: number;
    /** Number of critical issues still open */
    criticalIssues: number;
}
/**
 * Annotation thread structure for hierarchical display
 */
export interface AnnotationThread {
    /** Thread identifier */
    threadId: string;
    /** Root annotation starting the thread */
    rootAnnotation: Annotation;
    /** Nested reply annotations */
    replies: AnnotationThreadNode[];
    /** Thread metadata */
    metadata: {
        participantCount: number;
        lastActivity: string;
        status: AnnotationStatus;
        priority: AnnotationPriority;
    };
}
/**
 * Individual node in an annotation thread
 */
export interface AnnotationThreadNode {
    /** The annotation for this node */
    annotation: Annotation;
    /** Child reply nodes */
    replies: AnnotationThreadNode[];
    /** Depth level in the thread */
    level: number;
}
/**
 * Annotation validation result
 */
export interface AnnotationValidationResult {
    /** Whether the annotation is valid */
    isValid: boolean;
    /** Validation error messages */
    errors: string[];
}
/**
 * Batch annotation operation result
 */
export interface BatchAnnotationResult {
    /** Number of successful operations */
    successful: number;
    /** Number of failed operations */
    failed: number;
    /** Details of failed operations */
    failures: Array<{
        annotation: Annotation;
        error: string;
    }>;
}
/**
 * Annotation export format options
 */
export interface AnnotationExportOptions {
    /** Include resolved annotations */
    includeResolved?: boolean;
    /** Include rejected annotations */
    includeRejected?: boolean;
    /** Filter by priority levels */
    priorities?: AnnotationPriority[];
    /** Filter by annotation types */
    annotationTypes?: string[];
    /** Export format */
    format: 'json' | 'csv' | 'markdown' | 'html';
}
/**
 * Type guard to check if an object is an annotation
 */
export declare function isAnnotation(obj: unknown): obj is Annotation;
/**
 * Type guard to check if an annotation type URI is standard
 */
export declare function isStandardAnnotationType(uri: string): uri is StandardAnnotationType;
/**
 * Utility type for annotation collections
 */
export type AnnotationCollection = Annotation[];
/**
 * Utility type for annotation maps indexed by ID
 */
export type AnnotationMap = Map<string, Annotation>;
/**
 * Utility type for thread collections
 */
export type ThreadCollection = AnnotationThread[];
//# sourceMappingURL=annotations.d.ts.map