gerben
/
web-annotation-utils


			
				
					
						
						
							
							import type {
  OneOrMore,
  OneOrMoreIncluding,
  ZeroOrMore,
} from './multiplicity-utils.js';

/**
 * A Web Annotation object.
 *
 * This is an interpretation of the Web Annotation Data Model:
 * <https://www.w3.org/TR/2017/REC-annotation-model-20170223/>
 *
 * TODO Deal more systemically with ‘relations’, i.e. values that could be
 * either a nested object or a URI referring to such an object.
 */
export interface WebAnnotation {
  '@context': OneOrMoreIncluding<string, 'http://www.w3.org/ns/anno.jsonld'>;
  type: OneOrMoreIncluding<string, 'Annotation'>;
  id: string;
  target: OneOrMore<Target>;
  creator?: OneOrMore<Agent>;
  created?: UtcDateTime;
  generator?: OneOrMore<Agent>;
  generated?: UtcDateTime;
  modified?: UtcDateTime;
  motivation?: OneOrMore<Motivation>;
  audience?: ZeroOrMore<Audience>;
  rights?: ZeroOrMore<string>;
  canonical?: string;
  via?: ZeroOrMore<string>;
  body?: BodyChoice | OneOrMore<Body>;
  bodyValue?: string;
}

/**
 * A slightly stricter type for WebAnnotation, not allowing both a body and bodyValue.
 */
export type WebAnnotationStrict = WebAnnotation & (WithBody | WithBodyValue | WithoutBody);

interface WithBody {
  body: BodyChoice | OneOrMore<Body>;
  bodyValue?: undefined;
}

interface WithBodyValue {
  body?: undefined;
  bodyValue: string;
}

interface WithoutBody {
  body?: undefined;
  bodyValue?: undefined;
}

export type Body = string | BodyObject;

export type BodyObject = {
  creator?: OneOrMore<Agent>;
  created?: UtcDateTime;
  modified?: UtcDateTime;
  purpose?: OneOrMore<Motivation>;
} & (TextualBody | SpecificResource | ExternalResource);

export type Target = string | SpecificResource | ExternalResource;

export type Agent =
  | string
  | {
      id?: string;
      type?: OneOrMore<'Person' | 'Organization' | 'Software'>;
      name?: OneOrMore<string>;
      nickname?: OneOrMore<string>;
      email?: OneOrMore<string>;
      email_sha1?: OneOrMore<string>;
      homepage?: OneOrMore<string>;
    };

export type Audience =
  | string
  | {
      id?: string;
      type?: string;
    };

export interface BodyChoice {
  type: 'Choice';
  items: Body[];
}

export interface TextualBody extends Omit<ExternalResource, 'id' | 'type'> {
  id?: string;
  type: 'TextualBody';
  value: string;
}

export interface SpecificResource {
  id?: string;
  type?: 'SpecificResource';
  source: string;
  selector?: string | OneOrMore<Selector>;
  accessibility?: AccessibilityFeatures;
  rights?: ZeroOrMore<string>;
  canonical?: string;
  via?: ZeroOrMore<string>;
}

export interface Selector {
  type?: string;
  refinedBy?: Selector;
}

export interface ExternalResource {
  id: string;
  // XXX type’s value SHOULD be one of these, “but MAY come from other vocabularies”.
  type?: OneOrMore<'Dataset' | 'Image' | 'Video' | 'Sound' | 'Text'>;
  format?: OneOrMore<string>;
  language?: OneOrMore<string>;
  processingLanguage?: string;
  textDirection?: 'ltr' | 'rtl' | 'auto';
  accessibility?: AccessibilityFeatures;
  rights?: ZeroOrMore<string>;
  canonical?: string;
  via?: ZeroOrMore<string>;
}

export type Motivation =
  | 'assessing'
  | 'bookmarking'
  | 'classifying'
  | 'commenting'
  | 'describing'
  | 'editing'
  | 'highlighting'
  | 'identifying'
  | 'linking'
  | 'moderating'
  | 'questioning'
  | 'replying'
  | 'tagging';

// “The datetime MUST be a xsd:dateTime with the UTC timezone expressed as "Z".”
type UtcDateTime = `${string}Z`;
declare global {
  interface Date {
    toISOString(): UtcDateTime;
  }
}

// From <https://www.w3.org/2021/a11y-discov-vocab/latest/CG-FINAL-a11y-discov-vocab-20220610.html>
export type AccessibilityFeatures =
  | ZeroOrMore<AccessibilityFeature>
  | 'none'
  | ['none'];
export type AccessibilityFeature =
  | 'annotations'
  | 'ARIA'
  | 'bookmarks'
  | 'index'
  | 'printPageNumbers'
  | 'readingOrder'
  | 'structuralNavigation'
  | 'tableOfContents'
  | 'taggedPDF'
  | 'alternativeText'
  | 'audioDescription'
  | 'captions'
  | 'describedMath'
  | 'longDescription'
  | 'rubyAnnotations'
  | 'signLanguage'
  | 'transcript'
  | 'displayTransformability'
  | 'synchronizedAudioText'
  | 'timingControl'
  | 'unlocked'
  | 'ChemML'
  | 'latex'
  | 'MathML'
  | 'ttsMarkup'
  | 'highContrastAudio'
  | 'highContrastDisplay'
  | 'largePrint'
  | 'braille'
  | 'tactileGraphic'
  | 'tactileObject';