glossarist 0.4.39 → 0.4.40

package/package.json

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

package/src/models/designation.ts

@@ -0,0 +1,297 @@
+import { RegistrableModel } from './registrable.js';
+import { ConceptSource } from './concept-source.js';
+import type { ConceptSourceJson } from './concept-source.js';
+import { Pronunciation } from './pronunciation.js';
+import type { PronunciationJson } from './pronunciation.js';
+import { GrammarInfo } from './grammar-info.js';
+import type { GrammarInfoJson } from './grammar-info.js';
+import { RelatedConcept } from './related-concept.js';
+import type { RelatedConceptJson } from './related-concept.js';
+import {
+  DesignationRelationship,
+  DESIGNATION_RELATIONSHIP_TYPES,
+} from './designation-relationship.js';
+import type { DesignationRelationshipJson } from './designation-relationship.js';
+
+export type DesignationType =
+  | 'expression'
+  | 'abbreviation'
+  | 'symbol'
+  | 'letter_symbol'
+  | 'graphical symbol'
+  | 'graphical_symbol'
+  | string;
+
+export type NormativeStatus = 'preferred' | 'deprecated' | 'admitted' | 'deprecated_' | string | null;
+
+const SKOS_LABEL_BY_NORMATIVE_STATUS: Readonly<Record<string, string>> = Object.freeze({
+  preferred: 'prefLabel',
+  deprecated: 'hiddenLabel',
+  admitted: 'altLabel',
+  deprecated_: 'altLabel',
+});
+
+export interface DesignationJson {
+  type?: DesignationType;
+  designation?: string;
+  normative_status?: NormativeStatus;
+  normativeStatus?: NormativeStatus;
+  absent?: boolean | null;
+  field_of_application?: string | null;
+  fieldOfApplication?: string | null;
+  usage_info?: string | null;
+  usageInfo?: string | null;
+  geographical_area?: string | null;
+  geographicalArea?: string | null;
+  language?: string | null;
+  script?: string | null;
+  system?: string | null;
+  international?: boolean | null;
+  term_type?: string | null;
+  termType?: string | null;
+  pronunciation?: ReadonlyArray<PronunciationJson | Pronunciation>;
+  sources?: ReadonlyArray<ConceptSourceJson | ConceptSource>;
+  related?: ReadonlyArray<DesignationRelationshipJson | DesignationRelationship | RelatedConceptJson | RelatedConcept>;
+  prefix?: string | null;
+  grammar_info?: ReadonlyArray<GrammarInfoJson | GrammarInfo>;
+  acronym?: boolean;
+  initialism?: boolean;
+  truncation?: boolean;
+  text?: string | null;
+  image?: string | null;
+}
+
+export class Designation extends RegistrableModel {
+  readonly designation: string;
+  readonly type: DesignationType;
+  readonly normativeStatus: NormativeStatus;
+  readonly absent: boolean | null;
+  readonly fieldOfApplication: string | null;
+  readonly usageInfo: string | null;
+  readonly geographicalArea: string | null;
+  readonly language: string | null;
+  readonly script: string | null;
+  readonly system: string | null;
+  readonly international: boolean | null;
+  readonly termType: string | null;
+  readonly pronunciations: ReadonlyArray<Pronunciation>;
+  readonly sources: ReadonlyArray<ConceptSource>;
+  readonly related: ReadonlyArray<DesignationRelationship | RelatedConcept>;
+
+  constructor(data: DesignationJson = {}) {
+    super();
+    this.designation = data.designation ?? '';
+    this.type = data.type ?? 'expression';
+    this.normativeStatus = data.normative_status ?? data.normativeStatus ?? null;
+    this.absent = data.absent ?? null;
+    this.fieldOfApplication = data.field_of_application ?? data.fieldOfApplication ?? null;
+    this.usageInfo = data.usage_info ?? data.usageInfo ?? null;
+    this.geographicalArea = data.geographical_area ?? data.geographicalArea ?? null;
+    this.language = data.language ?? null;
+    this.script = data.script ?? null;
+    this.system = data.system ?? null;
+    this.international = data.international ?? null;
+    this.termType = data.term_type ?? data.termType ?? null;
+    this.pronunciations = (data.pronunciation ?? []).map((p) =>
+      p instanceof Pronunciation ? p : new Pronunciation(p as PronunciationJson),
+    );
+    this.sources = (data.sources ?? []).map((s) =>
+      s instanceof ConceptSource ? s : new ConceptSource(s as ConceptSourceJson),
+    );
+    this.related = (data.related ?? []).map((r) => {
+      if (r instanceof DesignationRelationship || r instanceof RelatedConcept) return r;
+      const hash = r as { type?: string };
+      if (hash?.type && DESIGNATION_RELATIONSHIP_TYPES.includes(hash.type)) {
+        return DesignationRelationship.fromJSON(hash as DesignationRelationshipJson);
+      }
+      return RelatedConcept.fromJSON(hash as RelatedConceptJson);
+    });
+  }
+
+  override toJSON(): DesignationJson {
+    const obj: DesignationJson = { type: this.type, designation: this.designation };
+    if (this.normativeStatus != null) obj.normative_status = this.normativeStatus;
+    if (this.absent != null) obj.absent = this.absent;
+    if (this.fieldOfApplication != null) obj.field_of_application = this.fieldOfApplication;
+    if (this.usageInfo != null) obj.usage_info = this.usageInfo;
+    if (this.geographicalArea != null) obj.geographical_area = this.geographicalArea;
+    if (this.language != null) obj.language = this.language;
+    if (this.script != null) obj.script = this.script;
+    if (this.system != null) obj.system = this.system;
+    if (this.international != null) obj.international = this.international;
+    if (this.termType != null) obj.term_type = this.termType;
+    if (this.pronunciations.length > 0) {
+      obj.pronunciation = this.pronunciations.map((p) => p.toJSON());
+    }
+    if (this.sources.length > 0) {
+      obj.sources = this.sources.map((s) => s.toJSON());
+    }
+    if (this.related.length > 0) {
+      obj.related = this.related.map((r) => r.toJSON() as never);
+    }
+    return obj;
+  }
+
+  /** RDF class local-name for this designation subtype. */
+  rdfClass(): string {
+    return 'Expression';
+  }
+
+  /** SKOS label predicate URI appropriate for this designation's normative status. */
+  skosLabelPredicate(skosNs: string): string {
+    return `${skosNs}${this._skosLabelLocalName()}`;
+  }
+
+  /** SKOS-XL label predicate URI. */
+  skosxlLabelPredicate(skosxlNs: string): string {
+    return `${skosxlNs}${this._skosLabelLocalName()}`;
+  }
+
+  protected _skosLabelLocalName(): string {
+    const statusVal = this.normativeStatus == null ? '' : String(this.normativeStatus);
+    const status = statusVal
+      .split(/[/#]/)
+      .pop() ?? '';
+    return SKOS_LABEL_BY_NORMATIVE_STATUS[status] ?? 'altLabel';
+  }
+
+  static identityOf(value: { type?: string; designation?: string } | null | undefined): string {
+    const v = value ?? {};
+    const type = v.type ?? 'expression';
+    const text = String(v.designation ?? '').toLowerCase().trim();
+    return `${type}|${text}`;
+  }
+
+  override identity(): string {
+    return Designation.identityOf(this);
+  }
+
+  static override fromJSON(data: DesignationJson): Designation {
+    return Designation.fromData(data);
+  }
+}
+
+export class Expression extends Designation {
+  readonly prefix: string | null;
+  readonly grammarInfo: ReadonlyArray<GrammarInfo>;
+
+  constructor(data: DesignationJson = {}) {
+    super(data);
+    this.prefix = data.prefix ?? null;
+    this.grammarInfo = (data.grammar_info ?? []).map((g) =>
+      g instanceof GrammarInfo ? g : new GrammarInfo(g as GrammarInfoJson),
+    );
+  }
+
+  override toJSON(): DesignationJson {
+    const obj = super.toJSON();
+    if (this.prefix != null) obj.prefix = this.prefix;
+    if (this.grammarInfo.length > 0) {
+      obj.grammar_info = this.grammarInfo.map((g) => g.toJSON());
+    }
+    return obj;
+  }
+
+  static override fromJSON(data: DesignationJson): Expression {
+    return new Expression(data);
+  }
+}
+
+Designation.register('expression', Expression);
+
+export class Abbreviation extends Expression {
+  readonly acronym: boolean;
+  readonly initialism: boolean;
+  readonly truncation: boolean;
+
+  constructor(data: DesignationJson = {}) {
+    super(data);
+    this.acronym = data.acronym ?? false;
+    this.initialism = data.initialism ?? false;
+    this.truncation = data.truncation ?? false;
+  }
+
+  override rdfClass(): string {
+    return 'Abbreviation';
+  }
+
+  override toJSON(): DesignationJson {
+    const obj = super.toJSON();
+    if (this.acronym) obj.acronym = true;
+    if (this.initialism) obj.initialism = true;
+    if (this.truncation) obj.truncation = true;
+    return obj;
+  }
+
+  static override fromJSON(data: DesignationJson): Abbreviation {
+    return new Abbreviation(data);
+  }
+}
+
+Designation.register('abbreviation', Abbreviation);
+
+export class Symbol extends Designation {
+  override rdfClass(): string {
+    return 'Symbol';
+  }
+
+  static override fromJSON(data: DesignationJson): Symbol {
+    return new Symbol(data);
+  }
+}
+
+Designation.register('symbol', Symbol);
+
+export class LetterSymbol extends Symbol {
+  readonly text: string | null;
+
+  constructor(data: DesignationJson = {}) {
+    super(data);
+    this.text = data.text ?? null;
+  }
+
+  override rdfClass(): string {
+    return 'LetterSymbol';
+  }
+
+  override toJSON(): DesignationJson {
+    const obj = super.toJSON();
+    if (this.text != null) obj.text = this.text;
+    return obj;
+  }
+
+  static override fromJSON(data: DesignationJson): LetterSymbol {
+    return new LetterSymbol(data);
+  }
+}
+
+Designation.register('letter_symbol', LetterSymbol);
+
+export class GraphicalSymbol extends Symbol {
+  readonly text: string | null;
+  readonly image: string | null;
+
+  constructor(data: DesignationJson = {}) {
+    super(data);
+    this.text = data.text ?? null;
+    this.image = data.image ?? null;
+  }
+
+  override rdfClass(): string {
+    return 'GraphicalSymbol';
+  }
+
+  override toJSON(): DesignationJson {
+    const obj = super.toJSON();
+    if (this.text != null) obj.text = this.text;
+    if (this.image != null) obj.image = this.image;
+    return obj;
+  }
+
+  static override fromJSON(data: DesignationJson): GraphicalSymbol {
+    return new GraphicalSymbol(data);
+  }
+}
+
+Designation.register('graphical symbol', GraphicalSymbol);
+Designation.register('graphical_symbol', GraphicalSymbol);

package/src/models/gcr-metadata.ts

@@ -0,0 +1,118 @@
+import * as yaml from 'js-yaml';
+import { GlossaristModel } from './base.js';
+import { GcrStatistics } from './gcr-statistics.js';
+import type { GcrStatisticsJson } from './gcr-statistics.js';
+
+export interface GcrMetadataJson {
+  shortname?: string | null;
+  version?: string | null;
+  title?: string | null;
+  description?: string | null;
+  owner?: string | null;
+  tags?: ReadonlyArray<string>;
+  concept_count?: number;
+  conceptCount?: number;
+  languages?: ReadonlyArray<string>;
+  created_at?: string | null;
+  createdAt?: string | null;
+  glossarist_version?: string | null;
+  glossaristVersion?: string | null;
+  schema_version?: string;
+  schemaVersion?: string;
+  homepage?: string | null;
+  repository?: string | null;
+  license?: string | null;
+  uri_prefix?: string | null;
+  uriPrefix?: string | null;
+  concept_uri_template?: string | null;
+  conceptUriTemplate?: string | null;
+  compiled_formats?: ReadonlyArray<string>;
+  compiledFormats?: ReadonlyArray<string>;
+  statistics?: GcrStatisticsJson | GcrStatistics | null;
+}
+
+export class GcrMetadata extends GlossaristModel {
+  readonly shortname: string | null;
+  readonly version: string | null;
+  readonly title: string | null;
+  readonly description: string | null;
+  readonly owner: string | null;
+  readonly tags: ReadonlyArray<string>;
+  readonly conceptCount: number;
+  readonly languages: ReadonlyArray<string>;
+  readonly createdAt: string | null;
+  readonly glossaristVersion: string | null;
+  readonly schemaVersion: string;
+  readonly homepage: string | null;
+  readonly repository: string | null;
+  readonly license: string | null;
+  readonly uriPrefix: string | null;
+  readonly conceptUriTemplate: string | null;
+  readonly compiledFormats: ReadonlyArray<string>;
+  readonly statistics: GcrStatistics | null;
+
+  constructor(data: GcrMetadataJson = {}) {
+    super();
+    this.shortname = data.shortname ?? null;
+    this.version = data.version ?? null;
+    this.title = data.title ?? null;
+    this.description = data.description ?? null;
+    this.owner = data.owner ?? null;
+    this.tags = (data.tags as ReadonlyArray<string>) ?? [];
+    this.conceptCount = data.concept_count ?? data.conceptCount ?? 0;
+    this.languages = (data.languages as ReadonlyArray<string>) ?? [];
+    this.createdAt = data.created_at ?? data.createdAt ?? null;
+    this.glossaristVersion = data.glossarist_version ?? data.glossaristVersion ?? null;
+    this.schemaVersion = data.schema_version ?? data.schemaVersion ?? '1';
+    this.homepage = data.homepage ?? null;
+    this.repository = data.repository ?? null;
+    this.license = data.license ?? null;
+    this.uriPrefix = data.uri_prefix ?? data.uriPrefix ?? null;
+    this.conceptUriTemplate = data.concept_uri_template ?? data.conceptUriTemplate ?? null;
+    this.compiledFormats = data.compiled_formats ?? data.compiledFormats ?? [];
+    this.statistics = data.statistics
+      ? data.statistics instanceof GcrStatistics
+        ? data.statistics
+        : new GcrStatistics(data.statistics as GcrStatisticsJson)
+      : null;
+  }
+
+  get concept_count(): number { return this.conceptCount; }
+  get created_at(): string | null { return this.createdAt; }
+  get glossarist_version(): string | null { return this.glossaristVersion; }
+  get schema_version(): string { return this.schemaVersion; }
+  get uri_prefix(): string | null { return this.uriPrefix; }
+  get concept_uri_template(): string | null { return this.conceptUriTemplate; }
+  get compiled_formats(): ReadonlyArray<string> { return this.compiledFormats; }
+
+  override toJSON(): GcrMetadataJson {
+    const obj: GcrMetadataJson = {};
+    if (this.shortname != null) obj.shortname = this.shortname;
+    if (this.version != null) obj.version = this.version;
+    if (this.title != null) obj.title = this.title;
+    if (this.description != null) obj.description = this.description;
+    if (this.owner != null) obj.owner = this.owner;
+    if (this.tags.length > 0) obj.tags = [...this.tags];
+    if (this.conceptCount > 0) obj.concept_count = this.conceptCount;
+    if (this.languages.length > 0) obj.languages = [...this.languages];
+    if (this.createdAt != null) obj.created_at = this.createdAt;
+    if (this.glossaristVersion != null) obj.glossarist_version = this.glossaristVersion;
+    if (this.schemaVersion != null) obj.schema_version = this.schemaVersion;
+    if (this.homepage != null) obj.homepage = this.homepage;
+    if (this.repository != null) obj.repository = this.repository;
+    if (this.license != null) obj.license = this.license;
+    if (this.uriPrefix != null) obj.uri_prefix = this.uriPrefix;
+    if (this.conceptUriTemplate != null) obj.concept_uri_template = this.conceptUriTemplate;
+    if (this.compiledFormats.length > 0) obj.compiled_formats = [...this.compiledFormats];
+    if (this.statistics != null) obj.statistics = this.statistics.toJSON();
+    return obj;
+  }
+
+  static override fromJSON(data: GcrMetadataJson): GcrMetadata {
+    return new GcrMetadata(data);
+  }
+
+  static fromYaml(yamlString: string): GcrMetadata {
+    return new GcrMetadata(yaml.load(yamlString) as GcrMetadataJson);
+  }
+}

package/src/models/gcr-statistics.ts

@@ -0,0 +1,76 @@
+import { GlossaristModel } from './base.js';
+
+export interface GcrStatisticsJson {
+  total_concepts?: number;
+  totalConcepts?: number;
+  concepts_with_definitions?: number;
+  conceptsWithDefinitions?: number;
+  concepts_by_status?: Record<string, number>;
+  conceptsByStatus?: Record<string, number>;
+}
+
+interface ConceptLike {
+  languages: ReadonlyArray<string>;
+  localization(lang: string): {
+    definitions: ReadonlyArray<unknown>;
+    entryStatus?: string | null;
+  } | null | undefined;
+}
+
+export class GcrStatistics extends GlossaristModel {
+  readonly totalConcepts: number;
+  readonly conceptsWithDefinitions: number;
+  readonly conceptsByStatus: Record<string, number>;
+
+  constructor(data: GcrStatisticsJson = {}) {
+    super();
+    this.totalConcepts = data.total_concepts ?? data.totalConcepts ?? 0;
+    this.conceptsWithDefinitions =
+      data.concepts_with_definitions ?? data.conceptsWithDefinitions ?? 0;
+    this.conceptsByStatus =
+      (data.concepts_by_status as Record<string, number>) ??
+      (data.conceptsByStatus as Record<string, number>) ??
+      {};
+  }
+
+  get total_concepts(): number { return this.totalConcepts; }
+  get concepts_with_definitions(): number { return this.conceptsWithDefinitions; }
+  get concepts_by_status(): Record<string, number> { return this.conceptsByStatus; }
+
+  override toJSON(): GcrStatisticsJson {
+    const obj: GcrStatisticsJson = { total_concepts: this.totalConcepts };
+    if (this.conceptsWithDefinitions > 0) {
+      obj.concepts_with_definitions = this.conceptsWithDefinitions;
+    }
+    if (Object.keys(this.conceptsByStatus).length > 0) {
+      obj.concepts_by_status = this.conceptsByStatus;
+    }
+    return obj;
+  }
+
+  static override fromJSON(data: GcrStatisticsJson): GcrStatistics {
+    return new GcrStatistics(data);
+  }
+
+  static fromConcepts(concepts: ReadonlyArray<ConceptLike>): GcrStatistics {
+    const langs = new Set<string>();
+    let withDefs = 0;
+    const byStatus: Record<string, number> = {};
+
+    for (const concept of concepts) {
+      for (const lang of concept.languages) {
+        langs.add(lang);
+        const lc = concept.localization(lang);
+        if (lc && lc.definitions.length > 0) withDefs++;
+        const status = lc?.entryStatus ?? 'unknown';
+        byStatus[status] = (byStatus[status] ?? 0) + 1;
+      }
+    }
+
+    return new GcrStatistics({
+      total_concepts: concepts.length,
+      concepts_with_definitions: withDefs,
+      concepts_by_status: byStatus,
+    });
+  }
+}

package/src/models/hyperedge-colors.ts

@@ -0,0 +1,87 @@
+// Hyperedge color resolver — resolves display colors for a
+// PartitiveHyperedge based on its enumeration and the carrying
+// concept's category color.
+
+import { categoryColorPair } from './relation-colors.js';
+import type { ColorPair } from './relation-colors.js';
+
+const ENUMERATION_INTENSITY: Readonly<Record<string, number>> = Object.freeze({
+  closed: 1.0,
+  open: 0.55,
+});
+
+const DEFAULT_CATEGORY = 'hierarchical';
+
+export interface ResolveHyperedgeColorOptions {
+  category?: string;
+  overrides?: { byCategory?: Record<string, Partial<ColorPair>> };
+}
+
+export interface ResolvedHyperedgeColor {
+  light: string;
+  dark: string;
+  pattern: 'dashed' | 'double' | null;
+}
+
+interface HyperedgeLike {
+  enumeration?: string;
+  markers?: ReadonlyArray<string>;
+}
+
+export function resolveHyperedgeColor(
+  hyperedge: HyperedgeLike | null,
+  options: ResolveHyperedgeColorOptions = {},
+): ResolvedHyperedgeColor | null {
+  if (!hyperedge) return null;
+
+  const category = options.category ?? DEFAULT_CATEGORY;
+  const base = categoryColorPair(category, options.overrides);
+  if (!base) return null;
+
+  const intensity = ENUMERATION_INTENSITY[hyperedge.enumeration ?? ''] ?? 1.0;
+  const pattern = derivePattern(hyperedge.markers);
+
+  return {
+    light: tint(base.light, intensity),
+    dark: tint(base.dark, intensity),
+    pattern,
+  };
+}
+
+function derivePattern(
+  markers: ReadonlyArray<string> | null | undefined,
+): 'dashed' | 'double' | null {
+  const arr = markers ?? [];
+  if (arr.includes('dashed')) return 'dashed';
+  if (arr.includes('double')) return 'double';
+  return null;
+}
+
+/**
+ * Linear interpolation between the base color and white (light mode)
+ * or between the base and a neutral (dark mode). Pure-string inputs
+ * return the original color when intensity === 1.0.
+ */
+function tint(hex: string, ratio: number): string {
+  if (ratio >= 1.0) return hex;
+  const rgb = parseHex(hex);
+  if (!rgb) return hex;
+
+  const target: ReadonlyArray<number> = [255, 255, 255];
+  const mixed = rgb.map((c, i) =>
+    Math.round(c + ((target[i] ?? 255) - c) * (1 - ratio)),
+  );
+  return '#' + mixed.map((c) => c.toString(16).padStart(2, '0')).join('');
+}
+
+function parseHex(s: string): [number, number, number] | null {
+  if (typeof s !== 'string') return null;
+  const m = s.match(/^#?([0-9a-f]{6})$/i);
+  if (!m) return null;
+  const n = m[1] as string;
+  return [
+    parseInt(n.slice(0, 2), 16),
+    parseInt(n.slice(2, 4), 16),
+    parseInt(n.slice(4, 6), 16),
+  ];
+}