glossarist 0.4.38 → 0.4.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.4.38",
+  "version": "0.4.39",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",

package/src/models/base.ts

@@ -7,9 +7,26 @@
  * override for performance.
  */
 
+/**
+ * Any value that can be the output of `JSON.stringify`. Used as the
+ * return type of {@link GlossaristModel.toJSON} so subclasses with
+ * non-object JSON output (e.g. `NonVerbalReference.toJSON()` returns
+ * a bare string for the no-display case) can override without
+ * breaking variance. The object case accepts any object to avoid
+ * forcing `<Model>Json` interfaces to declare explicit string index
+ * signatures (TS interfaces don't have implicit index signatures).
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | object;
+
 export abstract class GlossaristModel {
   /** Wire-shape serialization. Subclasses MUST override. */
-  toJSON(): object {
+  toJSON(): JsonValue {
     throw new Error(`${this.constructor.name} must implement toJSON()`);
   }
 

package/src/models/citation.ts

@@ -0,0 +1,98 @@
+import { GlossaristModel } from './base.js';
+import { Locality } from './locality.js';
+import type { LocalityJson } from './locality.js';
+
+export interface CitationRefJson {
+  source?: string | null;
+  id?: string | null;
+  version?: string | null;
+}
+
+export interface CitationJson {
+  ref?: CitationRefJson | CitationRef | null;
+  locality?: LocalityJson | Locality | null;
+  link?: string | null;
+  original?: string | null;
+  custom_locality?: string | null;
+  customLocality?: string | null;
+}
+
+export class CitationRef extends GlossaristModel {
+  readonly source: string | null;
+  readonly id: string | null;
+  readonly version: string | null;
+
+  constructor(data: CitationRefJson = {}) {
+    super();
+    this.source = data.source ?? null;
+    this.id = data.id ?? null;
+    this.version = data.version ?? null;
+  }
+
+  override toString(): string {
+    const parts: string[] = [];
+    if (this.source) parts.push(this.source);
+    if (this.id) parts.push(this.id);
+    return parts.join(' ');
+  }
+
+  override toJSON(): CitationRefJson {
+    const obj: CitationRefJson = {};
+    if (this.source != null) obj.source = this.source;
+    if (this.id != null) obj.id = this.id;
+    if (this.version != null) obj.version = this.version;
+    return obj;
+  }
+
+  static override fromJSON(data: CitationRefJson): CitationRef {
+    return new CitationRef(data);
+  }
+}
+
+export class Citation extends GlossaristModel {
+  /** Backward-compat alias for {@link CitationRef}. Original codebase
+   *  exposed the Ref class via `Citation.Ref`; keep that working. */
+  static readonly Ref = CitationRef;
+
+  readonly ref: CitationRef | null;
+  readonly locality: Locality | null;
+  readonly link: string | null;
+  readonly original: string | null;
+  readonly customLocality: string | null;
+
+  constructor(data: CitationJson | null = {}) {
+    super();
+    const d = data ?? {};
+    this.ref = d.ref
+      ? d.ref instanceof CitationRef
+        ? d.ref
+        : new CitationRef(d.ref)
+      : null;
+    this.locality = d.locality
+      ? d.locality instanceof Locality
+        ? d.locality
+        : new Locality(d.locality)
+      : null;
+    this.link = d.link ?? null;
+    this.original = d.original ?? null;
+    this.customLocality = d.custom_locality ?? d.customLocality ?? null;
+  }
+
+  override toString(): string {
+    return this.ref ? this.ref.toString() : '';
+  }
+
+  override toJSON(): CitationJson {
+    const obj: CitationJson = {};
+    if (this.ref != null) obj.ref = this.ref.toJSON();
+    if (this.locality != null) obj.locality = this.locality.toJSON();
+    if (this.link != null) obj.link = this.link;
+    if (this.original != null) obj.original = this.original;
+    if (this.customLocality != null) obj.custom_locality = this.customLocality;
+    return obj;
+  }
+
+  static override fromJSON(data: CitationJson): Citation {
+    return new Citation(data);
+  }
+}

package/src/models/{concept-reference.js → concept-reference.ts}

@@ -1,7 +1,21 @@
 import { GlossaristModel } from './base.js';
 
+export interface ConceptReferenceJson {
+  concept_id?: string | null;
+  conceptId?: string | null;
+  ref_type?: string | null;
+  refType?: string | null;
+  source?: string | null;
+  urn?: string | null;
+}
+
 export class ConceptReference extends GlossaristModel {
-  constructor(data = {}) {
+  readonly conceptId: string | null;
+  readonly refType: string | null;
+  readonly source: string | null;
+  readonly urn: string | null;
+
+  constructor(data: ConceptReferenceJson = {}) {
     super();
     this.conceptId = data.concept_id ?? data.conceptId ?? null;
     this.refType = data.ref_type ?? data.refType ?? null;
@@ -9,20 +23,20 @@ export class ConceptReference extends GlossaristModel {
     this.urn = data.urn ?? null;
   }
 
-  get isLocal() {
+  get isLocal(): boolean {
     return this.urn == null && this.source == null;
   }
 
-  get isExternal() {
+  get isExternal(): boolean {
     return !this.isLocal;
   }
 
-  static domain(conceptId) {
+  static domain(conceptId: string): ConceptReference {
     return new ConceptReference({ concept_id: conceptId, ref_type: 'domain' });
   }
 
-  toJSON() {
-    const obj = {};
+  override toJSON(): ConceptReferenceJson {
+    const obj: ConceptReferenceJson = {};
     if (this.conceptId != null) obj.concept_id = this.conceptId;
     if (this.refType != null) obj.ref_type = this.refType;
     if (this.source != null) obj.source = this.source;
@@ -30,7 +44,7 @@ export class ConceptReference extends GlossaristModel {
     return obj;
   }
 
-  static fromJSON(data) {
+  static override fromJSON(data: ConceptReferenceJson): ConceptReference {
     return new ConceptReference(data);
   }
 }

package/src/models/designation-relationship.ts

@@ -0,0 +1,39 @@
+import { GlossaristModel } from './base.js';
+
+export const DESIGNATION_RELATIONSHIP_TYPES: ReadonlyArray<string> = Object.freeze([
+  // TBX (ISO 30042) / ISO 12620 term-level relationships
+  'abbreviated_form_for', 'short_form_for',
+]);
+
+export type DesignationRelationshipType = string;
+
+export interface DesignationRelationshipJson {
+  type?: DesignationRelationshipType | null;
+  content?: string | null;
+  target?: string | null;
+}
+
+export class DesignationRelationship extends GlossaristModel {
+  readonly type: DesignationRelationshipType | null;
+  readonly content: string | null;
+  readonly target: string | null;
+
+  constructor(data: DesignationRelationshipJson = {}) {
+    super();
+    this.type = data.type ?? null;
+    this.content = data.content ?? null;
+    this.target = data.target ?? null;
+  }
+
+  override toJSON(): DesignationRelationshipJson {
+    const obj: DesignationRelationshipJson = {};
+    if (this.type != null) obj.type = this.type;
+    if (this.content != null) obj.content = this.content;
+    if (this.target != null) obj.target = this.target;
+    return obj;
+  }
+
+  static override fromJSON(data: DesignationRelationshipJson): DesignationRelationship {
+    return new DesignationRelationship(data);
+  }
+}

package/src/models/figure.ts

@@ -0,0 +1,110 @@
+import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
+import type { SharedNonVerbalEntityJson } from './shared-non-verbal-entity.js';
+import { NonVerbalEntity } from './non-verbal-entity.js';
+
+export interface FigureImageJson {
+  src?: string | null;
+  format?: string | null;
+  role?: string | null;
+  width?: number | string | null;
+  height?: number | string | null;
+  scale?: number | string | null;
+}
+
+export class FigureImage {
+  readonly src: string | null;
+  readonly format: string | null;
+  readonly role: string | null;
+  readonly width: number | string | null;
+  readonly height: number | string | null;
+  readonly scale: number | string | null;
+
+  constructor(data: FigureImageJson = {}) {
+    this.src = data.src ?? null;
+    this.format = data.format ?? null;
+    this.role = data.role ?? null;
+    this.width = data.width ?? null;
+    this.height = data.height ?? null;
+    this.scale = data.scale ?? null;
+  }
+
+  toJSON(): FigureImageJson {
+    const obj: FigureImageJson = {};
+    if (this.src != null) obj.src = this.src;
+    if (this.format != null) obj.format = this.format;
+    if (this.role != null) obj.role = this.role;
+    if (this.width != null) obj.width = this.width;
+    if (this.height != null) obj.height = this.height;
+    if (this.scale != null) obj.scale = this.scale;
+    return obj;
+  }
+
+  static fromJSON(data: FigureImageJson): FigureImage {
+    return new FigureImage(data);
+  }
+}
+
+export interface FigureJson extends SharedNonVerbalEntityJson {
+  images?: ReadonlyArray<FigureImageJson>;
+  subfigures?: ReadonlyArray<FigureJson | Figure>;
+}
+
+export class Figure extends SharedNonVerbalEntity {
+  protected readonly _rawImages: ReadonlyArray<FigureImageJson | FigureImage>;
+  protected readonly _rawSubfigures: ReadonlyArray<FigureJson | Figure>;
+  protected _images: ReadonlyArray<FigureImage> | null = null;
+  protected _subfigures: ReadonlyArray<Figure> | null = null;
+
+  constructor(data: FigureJson = {}) {
+    super(data);
+    this._rawImages = data.images ?? [];
+    this._rawSubfigures = data.subfigures ?? [];
+  }
+
+  override rdfClass(): string {
+    return 'Figure';
+  }
+
+  get images(): ReadonlyArray<FigureImage> {
+    return this._lazy<FigureImage>(
+      '_images',
+      '_rawImages',
+      (i) => (i instanceof FigureImage ? i : new FigureImage(i as FigureImageJson)),
+    );
+  }
+
+  get subfigures(): ReadonlyArray<Figure> {
+    return this._lazy<Figure>(
+      '_subfigures',
+      '_rawSubfigures',
+      (s) => (s instanceof Figure ? s : new Figure(s as FigureJson)),
+    );
+  }
+
+  override findById(targetId: string): this | null {
+    if (this.id === targetId) return this;
+    for (const sub of this.subfigures) {
+      const found = sub.findById(targetId);
+      if (found) return found as this;
+    }
+    return null;
+  }
+
+  override allIds(): string[] {
+    const ids = this.id != null ? [this.id] : [];
+    return [...ids, ...this.subfigures.flatMap((s) => s.allIds())];
+  }
+
+  override toJSON(): FigureJson {
+    const obj = super.toJSON() as FigureJson;
+    this._serialize(obj as unknown as Record<string, unknown>, 'images', '_images', '_rawImages');
+    this._serialize(obj as unknown as Record<string, unknown>, 'subfigures', '_subfigures', '_rawSubfigures');
+    return obj;
+  }
+
+  static override fromJSON(data: FigureJson): Figure {
+    return new Figure(data);
+  }
+}
+
+NonVerbalEntity.register('figure', Figure);

package/src/models/formula.ts

@@ -0,0 +1,36 @@
+import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
+import type { SharedNonVerbalEntityJson } from './shared-non-verbal-entity.js';
+import { NonVerbalEntity } from './non-verbal-entity.js';
+
+export interface FormulaJson extends SharedNonVerbalEntityJson {
+  expression?: string | null;
+  notation?: string | null;
+}
+
+export class Formula extends SharedNonVerbalEntity {
+  readonly expression: string | null;
+  readonly notation: string | null;
+
+  constructor(data: FormulaJson = {}) {
+    super(data);
+    this.expression = data.expression ?? null;
+    this.notation = data.notation ?? null;
+  }
+
+  override rdfClass(): string {
+    return 'Formula';
+  }
+
+  override toJSON(): FormulaJson {
+    const obj = super.toJSON() as FormulaJson;
+    if (this.expression != null) obj.expression = this.expression;
+    if (this.notation != null) obj.notation = this.notation;
+    return obj;
+  }
+
+  static override fromJSON(data: FormulaJson): Formula {
+    return new Formula(data);
+  }
+}
+
+NonVerbalEntity.register('formula', Formula);

package/src/models/non-verb-rep.ts

@@ -0,0 +1,48 @@
+import { NonVerbalEntity } from './non-verbal-entity.js';
+import type { NonVerbalEntityJson } from './non-verbal-entity.js';
+import { FigureImage } from './figure.js';
+import type { FigureImageJson } from './figure.js';
+
+export const NON_VERBAL_TYPES: ReadonlyArray<string> = Object.freeze([
+  'image', 'table', 'formula',
+]);
+
+export interface NonVerbRepJson extends NonVerbalEntityJson {
+  type?: string | null;
+  images?: ReadonlyArray<FigureImageJson | FigureImage>;
+}
+
+export class NonVerbRep extends NonVerbalEntity {
+  readonly type: string | null;
+  protected readonly _rawImages: ReadonlyArray<FigureImageJson | FigureImage>;
+  protected _images: ReadonlyArray<FigureImage> | null = null;
+
+  constructor(data: NonVerbRepJson = {}) {
+    super(data);
+    this.type = data.type ?? null;
+    this._rawImages = data.images ?? [];
+  }
+
+  override rdfClass(): string {
+    return 'NonVerbalRepresentation';
+  }
+
+  get images(): ReadonlyArray<FigureImage> {
+    return this._lazy<FigureImage>(
+      '_images',
+      '_rawImages',
+      (i) => (i instanceof FigureImage ? i : new FigureImage(i as FigureImageJson)),
+    );
+  }
+
+  override toJSON(): NonVerbRepJson {
+    const obj = super.toJSON() as NonVerbRepJson;
+    if (this.type != null) obj.type = this.type;
+    this._serialize(obj as unknown as Record<string, unknown>, 'images', '_images', '_rawImages');
+    return obj;
+  }
+
+  static override fromJSON(data: NonVerbRepJson): NonVerbRep {
+    return new NonVerbRep(data);
+  }
+}

package/src/models/non-verbal-entity.ts

@@ -0,0 +1,65 @@
+import { RegistrableModel } from './registrable.js';
+import { ConceptSource } from './concept-source.js';
+import type { ConceptSourceJson } from './concept-source.js';
+
+export interface NonVerbalEntityJson {
+  caption?: string | null;
+  description?: string | null;
+  alt?: string | null;
+  sources?: ReadonlyArray<ConceptSourceJson | ConceptSource>;
+  type?: string | null;
+}
+
+export class NonVerbalEntity extends RegistrableModel {
+  readonly caption: string | null;
+  readonly description: string | null;
+  readonly alt: string | null;
+  protected readonly _rawSources: ReadonlyArray<ConceptSourceJson | ConceptSource>;
+  protected _sources: ReadonlyArray<ConceptSource> | null = null;
+
+  constructor(data: NonVerbalEntityJson = {}) {
+    super();
+    this.caption = data.caption ?? null;
+    this.description = data.description ?? null;
+    this.alt = data.alt ?? null;
+    this._rawSources = data.sources ?? [];
+  }
+
+  get sources(): ReadonlyArray<ConceptSource> {
+    return this._lazy<ConceptSource>(
+      '_sources',
+      '_rawSources',
+      (s) => (s instanceof ConceptSource ? s : new ConceptSource(s as ConceptSourceJson)),
+    );
+  }
+
+  /**
+   * Ontology class local-name. Subtypes override to return their specific
+   * class (Figure/Table/Formula). Used by the RDF emitter so a new subtype
+   * registers without editing the emitter (OCP).
+   */
+  rdfClass(): string {
+    return 'NonVerbalEntity';
+  }
+
+  findById(_targetId: string): NonVerbalEntity | null {
+    return null;
+  }
+
+  allIds(): string[] {
+    return [];
+  }
+
+  override toJSON(): NonVerbalEntityJson {
+    const obj: NonVerbalEntityJson = {};
+    if (this.caption != null) obj.caption = this.caption;
+    if (this.description != null) obj.description = this.description;
+    if (this.alt != null) obj.alt = this.alt;
+    this._serialize(obj as unknown as Record<string, unknown>, 'sources', '_sources', '_rawSources');
+    return obj;
+  }
+
+  static override fromJSON(data: NonVerbalEntityJson): NonVerbalEntity {
+    return NonVerbalEntity.fromData(data);
+  }
+}

package/src/models/non-verbal-reference.ts

@@ -0,0 +1,73 @@
+import { RegistrableModel } from './registrable.js';
+
+export interface NonVerbalReferenceJson {
+  entityId?: string | null;
+  entity_id?: string | null;
+  ref?: string | null;
+  id?: string | null;
+  display?: string | null;
+  type?: string;
+}
+
+/**
+ * Polymorphic JSON for NonVerbalReference: either a bare string (the
+ * entity id) or an object with `{ ref, display?, type? }`.
+ */
+export type NonVerbalReferenceInput =
+  | NonVerbalReferenceJson
+  | string
+  | NonVerbalReference;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyCtor = new (...args: any[]) => any;
+
+export class NonVerbalReference extends RegistrableModel {
+  readonly entityId: string | null;
+  readonly display: string | null;
+
+  constructor(data: NonVerbalReferenceJson = {}) {
+    super();
+    this.entityId = data.entityId ?? data.entity_id ?? data.ref ?? data.id ?? null;
+    this.display = data.display ?? null;
+  }
+
+  get dedupKey(): [string, string | null] {
+    return [this.constructor.name, this.entityId];
+  }
+
+  override toJSON(): NonVerbalReferenceJson | string {
+    if (this.display != null) {
+      return { ref: this.entityId ?? '', display: this.display };
+    }
+    return this.entityId ?? '';
+  }
+
+  static override fromJSON<T extends NonVerbalReference>(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this: new (...args: any[]) => T,
+    data: NonVerbalReferenceInput,
+  ): T | NonVerbalReference {
+    if (data instanceof NonVerbalReference) return data;
+    if (typeof data === 'string') {
+      return new (this as new (d: NonVerbalReferenceJson) => T)({ entityId: data });
+    }
+    const entityId =
+      data.entityId ?? data.entity_id ?? data.ref ?? data.id ?? null;
+    const display = data.display ?? null;
+    const type = data.type;
+    const Self = this as unknown as { _registry(): Map<string, AnyCtor> };
+    if (type) {
+      const Cls = Self._registry().get(type);
+      if (Cls) {
+        return new (Cls as new (d: NonVerbalReferenceJson) => T)({
+          entityId: entityId ?? undefined,
+          display: display ?? undefined,
+        });
+      }
+    }
+    return new (this as new (d: NonVerbalReferenceJson) => T)({
+      entityId: entityId ?? undefined,
+      display: display ?? undefined,
+    });
+  }
+}

package/src/models/non-verbal-references.ts

@@ -0,0 +1,29 @@
+import { NonVerbalReference } from './non-verbal-reference.js';
+import type { NonVerbalReferenceInput } from './non-verbal-reference.js';
+
+export class FigureReference extends NonVerbalReference {
+  static override fromJSON(
+    data: NonVerbalReferenceInput,
+  ): FigureReference | NonVerbalReference {
+    return NonVerbalReference.fromJSON(data) as FigureReference | NonVerbalReference;
+  }
+}
+NonVerbalReference.register('figure', FigureReference);
+
+export class TableReference extends NonVerbalReference {
+  static override fromJSON(
+    data: NonVerbalReferenceInput,
+  ): TableReference | NonVerbalReference {
+    return NonVerbalReference.fromJSON(data) as TableReference | NonVerbalReference;
+  }
+}
+NonVerbalReference.register('table', TableReference);
+
+export class FormulaReference extends NonVerbalReference {
+  static override fromJSON(
+    data: NonVerbalReferenceInput,
+  ): FormulaReference | NonVerbalReference {
+    return NonVerbalReference.fromJSON(data) as FormulaReference | NonVerbalReference;
+  }
+}
+NonVerbalReference.register('formula', FormulaReference);

package/src/models/registrable.ts

@@ -0,0 +1,48 @@
+import { GlossaristModel } from './base.js';
+
+/**
+ * Per-class registry of named subtypes. The registry is keyed by
+ * `type` discriminator and maps to the constructor function. Used by
+ * NonVerbalEntity (Figure/Table/Formula), NonVerbalReference
+ * (Figure/Table/Formula references), and any future RegistrableModel
+ * subclass that needs polymorphic dispatch on a string discriminator.
+ *
+ * Stored as a WeakMap keyed by the base class function, so each base
+ * gets its own namespace (NonVerbalEntity.register does not collide
+ * with NonVerbalReference.register).
+ *
+ * The registry stores constructors as `Function` because TS's strict
+ * variance on constructor params makes a typed constraint reject
+ * subclasses with narrower param types. The dispatch site casts the
+ * result back to the specific subclass.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- see docstring.
+type AnyCtor = new (...args: any[]) => any;
+
+const _registries = new WeakMap<object, Map<string, AnyCtor>>();
+
+export class RegistrableModel extends GlossaristModel {
+  static _registry(): Map<string, AnyCtor> {
+    const existing = _registries.get(this) ?? new Map();
+    if (!_registries.has(this)) _registries.set(this, existing);
+    return existing;
+  }
+
+  static register(type: string, cls: AnyCtor): void {
+    this._registry().set(type, cls);
+  }
+
+  static fromData<T extends RegistrableModel>(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- any ctor signature accepted.
+    this: new (...args: any[]) => T,
+    data: unknown,
+  ): T {
+    if (data instanceof this) return data;
+    const type = (data as { type?: string } | null)?.type;
+    const Self = this as unknown as { _registry(): Map<string, AnyCtor> };
+    const registry = Self._registry();
+    const Cls = type ? (registry.get(type) ?? (this as AnyCtor)) : (this as AnyCtor);
+    return new (Cls as new (data: unknown) => T)(data);
+  }
+}

package/src/models/{related-concept.js → related-concept.ts}

@@ -1,7 +1,9 @@
 import { GlossaristModel } from './base.js';
 import { ConceptRef } from './concept-ref.js';
+import type { ConceptRefJson } from './concept-ref.js';
+import type { LocalizedString } from './generic-member.js';
 
-export const RELATIONSHIP_TYPES = Object.freeze([
+export const RELATIONSHIP_TYPES: ReadonlyArray<string> = Object.freeze([
   // Lifecycle (ISO 10241-1)
   'deprecates', 'deprecated_by', 'supersedes', 'superseded_by',
   'replaces', 'replaced_by', 'invalidates', 'invalidated_by',
@@ -25,10 +27,9 @@ export const RELATIONSHIP_TYPES = Object.freeze([
   // Associative (ISO 10241-1 / ISO 25964)
   'see', 'related_concept', 'related_concept_broader', 'related_concept_narrower',
   'references',
-  // ExternalConcept resolution (Glossarist extension — v2 partitive-relation)
-  // Direction: real concept `provides` substance for an external concept;
-  // external concept `provided_by` real concept. Stored on the
-  // ExternalConcept. See TODO.partitive-relation-v2 item 07.
+  // ExternalConcept resolution (Glossarist extension). Direction: real
+  // concept `provides` substance for an external concept; external concept
+  // `provided_by` real concept. Stored on the ExternalConcept.
   'provides', 'provided_by',
   // Comparative (ISO 10241-1)
   'compare', 'contrast',
@@ -38,56 +39,79 @@ export const RELATIONSHIP_TYPES = Object.freeze([
   'homograph', 'false_friend',
 ]);
 
+export type RelationshipType = string;
+
+export interface RelatedConceptJson {
+  type?: RelationshipType;
+  content?: LocalizedString | string | null;
+  ref?: ConceptRefJson | ConceptRef | null;
+}
+
 export class RelatedConcept extends GlossaristModel {
-  constructor(data = {}) {
+  readonly type: RelationshipType;
+  readonly content: LocalizedString | null;
+  readonly ref: ConceptRef | null;
+
+  constructor(data: RelatedConceptJson = {}) {
     super();
     this.type = data.type ?? 'see';
-    this.content = normalizeContent(data.content);
+    this.content = _normalizeContent(data.content);
     this.ref = data.ref
-      ? (data.ref instanceof ConceptRef ? data.ref : new ConceptRef(data.ref))
+      ? data.ref instanceof ConceptRef
+        ? data.ref
+        : new ConceptRef(data.ref)
       : null;
   }
 
-  // Convenience reader: returns the first available string value
-  // from the localized hash, or null if absent. Mirrors
-  // PartitiveHyperedge#contentString.
-  get contentString() {
+  /**
+   * Convenience reader: returns the first available string value from
+   * the localized hash, or null if absent.
+   */
+  get contentString(): string | null {
     if (!this.content) return null;
     const values = Object.values(this.content);
-    return values.length > 0 ? values[0] : null;
+    return values.length > 0 ? (values[0] ?? null) : null;
   }
 
-  toJSON() {
-    const obj = { type: this.type };
+  override toJSON(): RelatedConceptJson {
+    const obj: RelatedConceptJson = { type: this.type };
     if (this.content != null) obj.content = this.content;
     if (this.ref != null) obj.ref = this.ref.toJSON();
     return obj;
   }
 
-  static identityOf(value) {
+  static identityOf(
+    value: {
+      type?: string;
+      ref?: { source?: string | null; id?: string | null } | null;
+    } | null | undefined,
+  ): string {
     const v = value ?? {};
-    const ref = v?.ref;
+    const ref = v.ref;
     return `${v.type ?? ''}|${ref?.source ?? ''}|${ref?.id ?? ''}`;
   }
 
-  identity() {
+  override identity(): string {
     return RelatedConcept.identityOf(this);
   }
 
-  static fromJSON(data) {
+  static override fromJSON(data: RelatedConceptJson): RelatedConcept {
     return new RelatedConcept(data);
   }
 }
 
-// Content is a localized string (language → text). Plain strings on
-// input are normalized to `{ default: '...' }` so callers always see
-// the same shape. Mirrors PartitiveHyperedge's normalizeContent.
-function normalizeContent(value) {
+function _normalizeContent(
+  value: LocalizedString | string | null | undefined,
+): LocalizedString | null {
   if (value == null) return null;
   if (typeof value === 'string') return { default: value };
   if (typeof value === 'object') {
-    const entries = Object.entries(value).filter(([, v]) => typeof v === 'string');
-    return entries.length > 0 ? Object.fromEntries(entries) : null;
+    const entries = Object.entries(value).filter(
+      ([, v]) => typeof v === 'string',
+    );
+    return entries.length > 0
+      ? (Object.fromEntries(entries) as LocalizedString)
+      : null;
   }
   return null;
 }

package/src/models/shared-non-verbal-entity.ts

@@ -0,0 +1,36 @@
+import { NonVerbalEntity } from './non-verbal-entity.js';
+import type { NonVerbalEntityJson } from './non-verbal-entity.js';
+
+export interface SharedNonVerbalEntityJson extends NonVerbalEntityJson {
+  id?: string | null;
+  identifier?: string | null;
+}
+
+export class SharedNonVerbalEntity extends NonVerbalEntity {
+  readonly id: string | null;
+  readonly identifier: string | null;
+
+  constructor(data: SharedNonVerbalEntityJson = {}) {
+    super(data);
+    this.id = data.id ?? null;
+    this.identifier = data.identifier ?? null;
+  }
+
+  override findById(targetId: string): this | null {
+    return this.id === targetId ? this : null;
+  }
+  override allIds(): string[] {
+    return this.id != null ? [this.id] : [];
+  }
+
+  override toJSON(): SharedNonVerbalEntityJson {
+    const obj = super.toJSON() as SharedNonVerbalEntityJson;
+    if (this.id != null) obj.id = this.id;
+    if (this.identifier != null) obj.identifier = this.identifier;
+    return obj;
+  }
+
+  static override fromJSON(data: SharedNonVerbalEntityJson): SharedNonVerbalEntity {
+    return SharedNonVerbalEntity.fromData(data);
+  }
+}

package/src/models/table.ts

@@ -0,0 +1,36 @@
+import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
+import type { SharedNonVerbalEntityJson } from './shared-non-verbal-entity.js';
+import { NonVerbalEntity } from './non-verbal-entity.js';
+
+export interface TableJson extends SharedNonVerbalEntityJson {
+  content?: string | null;
+  format?: string | null;
+}
+
+export class Table extends SharedNonVerbalEntity {
+  readonly content: string | null;
+  readonly format: string | null;
+
+  constructor(data: TableJson = {}) {
+    super(data);
+    this.content = data.content ?? null;
+    this.format = data.format ?? null;
+  }
+
+  override rdfClass(): string {
+    return 'Table';
+  }
+
+  override toJSON(): TableJson {
+    const obj = super.toJSON() as TableJson;
+    if (this.content != null) obj.content = this.content;
+    if (this.format != null) obj.format = this.format;
+    return obj;
+  }
+
+  static override fromJSON(data: TableJson): Table {
+    return new Table(data);
+  }
+}
+
+NonVerbalEntity.register('table', Table);

package/src/models/citation.js

@@ -1,68 +0,0 @@
-import { GlossaristModel } from './base.js';
-import { Locality } from './locality.js';
-
-export class Citation extends GlossaristModel {
-  constructor(data = {}) {
-    super();
-    const d = data ?? {};
-
-    this.ref = d.ref
-      ? (d.ref instanceof Citation.Ref ? d.ref : new Citation.Ref(d.ref))
-      : null;
-
-    this.locality = d.locality
-      ? (d.locality instanceof Locality ? d.locality : new Locality(d.locality))
-      : null;
-    this.link = d.link ?? null;
-    this.original = d.original ?? null;
-    this.customLocality = d.custom_locality ?? d.customLocality ?? null;
-  }
-
-  toString() {
-    if (this.ref) return this.ref.toString();
-    return '';
-  }
-
-  toJSON() {
-    const obj = {};
-    if (this.ref != null) obj.ref = this.ref.toJSON();
-    if (this.locality != null) obj.locality = this.locality.toJSON();
-    if (this.link != null) obj.link = this.link;
-    if (this.original != null) obj.original = this.original;
-    if (this.customLocality != null) obj.custom_locality = this.customLocality;
-    return obj;
-  }
-
-  static fromJSON(data) {
-    return new Citation(data);
-  }
-}
-
-Citation.Ref = class Ref extends GlossaristModel {
-  constructor(data = {}) {
-    super();
-    const d = data ?? {};
-    this.source = d.source ?? null;
-    this.id = d.id ?? null;
-    this.version = d.version ?? null;
-  }
-
-  toString() {
-    const parts = [];
-    if (this.source) parts.push(this.source);
-    if (this.id) parts.push(this.id);
-    return parts.join(' ');
-  }
-
-  toJSON() {
-    const obj = {};
-    if (this.source != null) obj.source = this.source;
-    if (this.id != null) obj.id = this.id;
-    if (this.version != null) obj.version = this.version;
-    return obj;
-  }
-
-  static fromJSON(data) {
-    return new Citation.Ref(data);
-  }
-};

package/src/models/designation-relationship.js

@@ -1,27 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export const DESIGNATION_RELATIONSHIP_TYPES = Object.freeze([
-  // TBX (ISO 30042) / ISO 12620 term-level relationships
-  'abbreviated_form_for', 'short_form_for',
-]);
-
-export class DesignationRelationship extends GlossaristModel {
-  constructor(data = {}) {
-    super();
-    this.type = data.type ?? null;
-    this.content = data.content ?? null;
-    this.target = data.target ?? null;
-  }
-
-  toJSON() {
-    const obj = {};
-    if (this.type != null) obj.type = this.type;
-    if (this.content != null) obj.content = this.content;
-    if (this.target != null) obj.target = this.target;
-    return obj;
-  }
-
-  static fromJSON(data) {
-    return new DesignationRelationship(data);
-  }
-}

package/src/models/figure.js

@@ -1,75 +0,0 @@
-import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
-import { NonVerbalEntity } from './non-verbal-entity.js';
-
-export class FigureImage {
-  constructor(data = {}) {
-    this.src = data.src ?? null;
-    this.format = data.format ?? null;
-    this.role = data.role ?? null;
-    this.width = data.width ?? null;
-    this.height = data.height ?? null;
-    this.scale = data.scale ?? null;
-  }
-
-  toJSON() {
-    const obj = {};
-    if (this.src != null) obj.src = this.src;
-    if (this.format != null) obj.format = this.format;
-    if (this.role != null) obj.role = this.role;
-    if (this.width != null) obj.width = this.width;
-    if (this.height != null) obj.height = this.height;
-    if (this.scale != null) obj.scale = this.scale;
-    return obj;
-  }
-
-  static fromJSON(data) { return new FigureImage(data); }
-}
-
-export class Figure extends SharedNonVerbalEntity {
-  constructor(data = {}) {
-    super(data);
-    this._rawImages = data.images ?? [];
-    this._rawSubfigures = data.subfigures ?? [];
-    this._images = null;
-    this._subfigures = null;
-  }
-
-  rdfClass() {
-    return 'Figure';
-  }
-
-  get images() {
-    return this._lazy('_images', '_rawImages',
-      i => i instanceof FigureImage ? i : new FigureImage(i));
-  }
-
-  get subfigures() {
-    return this._lazy('_subfigures', '_rawSubfigures',
-      s => s instanceof Figure ? s : new Figure(s));
-  }
-
-  findById(targetId) {
-    if (this.id === targetId) return this;
-    for (const sub of this.subfigures) {
-      const found = sub.findById(targetId);
-      if (found) return found;
-    }
-    return null;
-  }
-
-  allIds() {
-    const ids = this.id != null ? [this.id] : [];
-    return [...ids, ...this.subfigures.flatMap(s => s.allIds())];
-  }
-
-  toJSON() {
-    const obj = super.toJSON();
-    this._serialize(obj, 'images', '_images', '_rawImages');
-    this._serialize(obj, 'subfigures', '_subfigures', '_rawSubfigures');
-    return obj;
-  }
-
-  static fromJSON(data) { return new Figure(data); }
-}
-
-NonVerbalEntity.register('figure', Figure);

package/src/models/formula.js

@@ -1,25 +0,0 @@
-import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
-import { NonVerbalEntity } from './non-verbal-entity.js';
-
-export class Formula extends SharedNonVerbalEntity {
-  constructor(data = {}) {
-    super(data);
-    this.expression = data.expression ?? null;
-    this.notation = data.notation ?? null;
-  }
-
-  rdfClass() {
-    return 'Formula';
-  }
-
-  toJSON() {
-    const obj = super.toJSON();
-    if (this.expression != null) obj.expression = this.expression;
-    if (this.notation != null) obj.notation = this.notation;
-    return obj;
-  }
-
-  static fromJSON(data) { return new Formula(data); }
-}
-
-NonVerbalEntity.register('formula', Formula);

package/src/models/non-verb-rep.js

@@ -1,33 +0,0 @@
-import { NonVerbalEntity } from './non-verbal-entity.js';
-import { FigureImage } from './figure.js';
-
-export const NON_VERBAL_TYPES = Object.freeze(['image', 'table', 'formula']);
-
-export class NonVerbRep extends NonVerbalEntity {
-  constructor(data = {}) {
-    super(data);
-    this.type = data.type ?? null;
-    this._rawImages = data.images ?? [];
-    this._images = null;
-  }
-
-  rdfClass() {
-    return 'NonVerbalRepresentation';
-  }
-
-  get images() {
-    return this._lazy('_images', '_rawImages',
-      i => i instanceof FigureImage ? i : new FigureImage(i));
-  }
-
-  toJSON() {
-    const obj = super.toJSON();
-    if (this.type != null) obj.type = this.type;
-    this._serialize(obj, 'images', '_images', '_rawImages');
-    return obj;
-  }
-
-  static fromJSON(data) {
-    return new NonVerbRep(data);
-  }
-}

package/src/models/non-verbal-entity.js

@@ -1,46 +0,0 @@
-import { RegistrableModel } from './registrable.js';
-import { ConceptSource } from './concept-source.js';
-
-export class NonVerbalEntity extends RegistrableModel {
-  constructor(data = {}) {
-    super();
-    this.caption = data.caption ?? null;
-    this.description = data.description ?? null;
-    this.alt = data.alt ?? null;
-    this._rawSources = data.sources ?? [];
-    this._sources = null;
-  }
-
-  get sources() {
-    return this._lazy('_sources', '_rawSources',
-      s => s instanceof ConceptSource ? s : new ConceptSource(s));
-  }
-
-  // Ontology class local-name. Subtypes override to return their specific
-  // class (Figure/Table/Formula). Used by the RDF emitter so a new subtype
-  // registers without editing the emitter (OCP).
-  rdfClass() {
-    return 'NonVerbalEntity';
-  }
-
-  findById(_targetId) {
-    return null;
-  }
-
-  allIds() {
-    return [];
-  }
-
-  toJSON() {
-    const obj = {};
-    if (this.caption != null) obj.caption = this.caption;
-    if (this.description != null) obj.description = this.description;
-    if (this.alt != null) obj.alt = this.alt;
-    this._serialize(obj, 'sources', '_sources', '_rawSources');
-    return obj;
-  }
-
-  static fromJSON(data) {
-    return NonVerbalEntity.fromData(data);
-  }
-}

package/src/models/non-verbal-reference.js

@@ -1,35 +0,0 @@
-import { RegistrableModel } from './registrable.js';
-
-export class NonVerbalReference extends RegistrableModel {
-  constructor(data = {}) {
-    super();
-    this.entityId = data.entityId ?? data.entity_id ?? data.ref ?? data.id ?? null;
-    this.display = data.display ?? null;
-  }
-
-  get dedupKey() {
-    return [this.constructor.name, this.entityId];
-  }
-
-  toJSON() {
-    if (this.display != null) {
-      return { ref: this.entityId, display: this.display };
-    }
-    return this.entityId;
-  }
-
-  static fromJSON(data) {
-    if (data instanceof NonVerbalReference) return data;
-    if (typeof data === 'string') {
-      return new NonVerbalReference({ entityId: data });
-    }
-    const entityId = data.entityId ?? data.entity_id ?? data.ref ?? data.id ?? null;
-    const display = data.display ?? null;
-    const type = data.type;
-    if (type && this._registry().has(type)) {
-      const Cls = this._registry().get(type);
-      return new Cls({ entityId, display });
-    }
-    return new NonVerbalReference({ entityId, display });
-  }
-}

package/src/models/non-verbal-references.js

@@ -1,16 +0,0 @@
-import { NonVerbalReference } from './non-verbal-reference.js';
-
-export class FigureReference extends NonVerbalReference {
-  static fromJSON(data) { return NonVerbalReference.fromJSON(data); }
-}
-NonVerbalReference.register('figure', FigureReference);
-
-export class TableReference extends NonVerbalReference {
-  static fromJSON(data) { return NonVerbalReference.fromJSON(data); }
-}
-NonVerbalReference.register('table', TableReference);
-
-export class FormulaReference extends NonVerbalReference {
-  static fromJSON(data) { return NonVerbalReference.fromJSON(data); }
-}
-NonVerbalReference.register('formula', FormulaReference);

package/src/models/registrable.js

@@ -1,25 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-const _registries = new WeakMap();
-
-export class RegistrableModel extends GlossaristModel {
-  static _registry() {
-    let map = _registries.get(this);
-    if (!map) {
-      map = new Map();
-      _registries.set(this, map);
-    }
-    return map;
-  }
-
-  static register(type, cls) {
-    this._registry().set(type, cls);
-  }
-
-  static fromData(data) {
-    if (data instanceof this) return data;
-    const type = data?.type;
-    const Cls = type ? this._registry().get(type) ?? this : this;
-    return new Cls(data);
-  }
-}

package/src/models/shared-non-verbal-entity.js

@@ -1,28 +0,0 @@
-import { NonVerbalEntity } from './non-verbal-entity.js';
-
-export class SharedNonVerbalEntity extends NonVerbalEntity {
-  constructor(data = {}) {
-    super(data);
-    this.id = data.id ?? null;
-    this.identifier = data.identifier ?? null;
-  }
-
-  findById(targetId) {
-    return this.id === targetId ? this : null;
-  }
-
-  allIds() {
-    return this.id != null ? [this.id] : [];
-  }
-
-  toJSON() {
-    const obj = super.toJSON();
-    if (this.id != null) obj.id = this.id;
-    if (this.identifier != null) obj.identifier = this.identifier;
-    return obj;
-  }
-
-  static fromJSON(data) {
-    return SharedNonVerbalEntity.fromData(data);
-  }
-}

package/src/models/table.js

@@ -1,25 +0,0 @@
-import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
-import { NonVerbalEntity } from './non-verbal-entity.js';
-
-export class Table extends SharedNonVerbalEntity {
-  constructor(data = {}) {
-    super(data);
-    this.content = data.content ?? null;
-    this.format = data.format ?? null;
-  }
-
-  rdfClass() {
-    return 'Table';
-  }
-
-  toJSON() {
-    const obj = super.toJSON();
-    if (this.content != null) obj.content = this.content;
-    if (this.format != null) obj.format = this.format;
-    return obj;
-  }
-
-  static fromJSON(data) { return new Table(data); }
-}
-
-NonVerbalEntity.register('table', Table);