@glossarist/concept-browser 0.7.51 → 0.7.52

package/src/errors.ts

@@ -0,0 +1,136 @@
+export interface ErrorContext {
+  readonly conceptId?: string;
+  readonly registerId?: string;
+  readonly locale?: string;
+  readonly predicate?: string;
+  readonly sourcePath?: string;
+  readonly cause?: unknown;
+  readonly [key: string]: unknown;
+}
+
+export class GlossaristError extends Error {
+  constructor(
+    message: string,
+    public readonly context: ErrorContext = {},
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+
+  hint(): string {
+    return '';
+  }
+}
+
+export class ConfigurationError extends GlossaristError {}
+export class DataSourceError extends GlossaristError {}
+export class SerializationError extends GlossaristError {}
+export class ValidationError extends GlossaristError {}
+
+export class UnknownDatasetError extends ConfigurationError {
+  static make(registerId: string): UnknownDatasetError {
+    return new UnknownDatasetError(`Unknown dataset: ${registerId}`, { registerId });
+  }
+
+  hint(): string {
+    return 'Check datasets.yml / datasets.json registration and adapter discovery.';
+  }
+}
+
+export class DatasetRegistryLoadError extends DataSourceError {
+  static make(status: number, url?: string): DatasetRegistryLoadError {
+    return new DatasetRegistryLoadError(
+      `Failed to load dataset registry: HTTP ${status}`,
+      { status, url },
+    );
+  }
+}
+
+export class ManifestLoadError extends DataSourceError {
+  static make(registerId: string, status: number): ManifestLoadError {
+    return new ManifestLoadError(
+      `Failed to load manifest for ${registerId}: HTTP ${status}`,
+      { registerId, status },
+    );
+  }
+}
+
+export class IndexLoadError extends DataSourceError {
+  static make(registerId: string, status: number): IndexLoadError {
+    return new IndexLoadError(
+      `Failed to load index for ${registerId}: HTTP ${status}`,
+      { registerId, status },
+    );
+  }
+}
+
+export class ChunkLoadError extends DataSourceError {
+  static make(registerId: string, chunkIndex: number, status: number): ChunkLoadError {
+    return new ChunkLoadError(
+      `Failed to load chunk ${chunkIndex} for ${registerId}: HTTP ${status}`,
+      { registerId, chunkIndex, status },
+    );
+  }
+}
+
+export class ConceptNotFoundError extends DataSourceError {
+  static make(registerId: string, conceptId: string): ConceptNotFoundError {
+    return new ConceptNotFoundError(
+      `Concept ${conceptId} not found in ${registerId}`,
+      { registerId, conceptId },
+    );
+  }
+}
+
+export class NonVerbalEntityNotFoundError extends DataSourceError {
+  static make(datasetId: string, kind: string, entityId: string, status: number): NonVerbalEntityNotFoundError {
+    return new NonVerbalEntityNotFoundError(
+      `Failed to load ${kind} ${entityId} from ${datasetId}: HTTP ${status}`,
+      { datasetId, kind, entityId, status },
+    );
+  }
+}
+
+export class InvalidConceptIdentityError extends SerializationError {
+  hint(): string {
+    return 'ConceptIdentity requires non-empty localId, registerId, and uriBase.';
+  }
+}
+
+export class InvalidConceptUriError extends SerializationError {
+  static make(uri: string): InvalidConceptUriError {
+    return new InvalidConceptUriError(`Not a concept URI: ${uri}`, { uri });
+  }
+
+  hint(): string {
+    return 'Expected format: <uriBase>/<registerId>/concept/<conceptId>';
+  }
+}
+
+export class InvalidLangTagError extends SerializationError {
+  hint(): string {
+    return 'Use BCP-47 form: primary[-script][-region][-variant]*[-x-private]. ' +
+      'ISO 639-3 codes (eng, fra) are normalized to ISO 639-1 (en, fr).';
+  }
+}
+
+export function isGlossaristError(err: unknown): err is GlossaristError {
+  return err instanceof GlossaristError;
+}
+
+export function formatError(err: GlossaristError): string {
+  const lines = [`${err.name}: ${err.message}`];
+  const fields: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(err.context)) {
+    if (k === 'cause' || v === undefined || v === null) continue;
+    fields[k] = v;
+  }
+  if (Object.keys(fields).length) {
+    for (const [k, v] of Object.entries(fields)) {
+      lines.push(`  ${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`);
+    }
+  }
+  const h = err.hint();
+  if (h) lines.push(`  hint: ${h}`);
+  return lines.join('\n');
+}

package/src/i18n/locales/eng.yml

@@ -97,6 +97,12 @@ concept.failedToLoad: Failed to load concept
 concept.notFound: Concept not found
 concept.notFoundMsg: "The concept \"{id}\" does not exist in this dataset."
 concept.backToDataset: Back to dataset
+concept.editionSeries: Edition series
+concept.viewing: viewing
+concept.currentEdition: current edition
+edge.supersedes: supersedes
+edge.superseded_by: superseded by
+concept.noChain: No supersession chain recorded for this concept.
 
 # Sidebar
 sidebar.overview: Overview
@@ -185,3 +191,21 @@ dataset.alphabetical: Alphabetical
 dataset.sectionFilter: Section
 dataset.clearSection: Clear section
 dataset.conceptsInSection: concepts in section
+
+# Relation sphere view
+sphere.viewOptions: View options
+sphere.degree: Degree
+sphere.language: Language
+sphere.datasets: Datasets
+sphere.relationTypes: Relation types
+sphere.expand: Expand
+sphere.tight: tight
+sphere.loose: loose
+sphere.redraw: Redraw
+sphere.focus: FOCUS
+concept.detailView: Detail
+concept.relationSphere: Relation Sphere
+concept.permalink: Permalink
+concept.copied: Copied
+
+# Relation types (displayed in legend + edge labels)

package/src/i18n/locales/fra.yml

@@ -97,6 +97,12 @@ concept.failedToLoad: Échec du chargement du concept
 concept.notFound: Concept non trouvé
 concept.notFoundMsg: "Le concept « {id} » n'existe pas dans ce jeu de données."
 concept.backToDataset: Retour au jeu de données
+concept.editionSeries: Série d'éditions
+concept.viewing: affiché
+concept.currentEdition: édition courante
+edge.supersedes: remplace
+edge.superseded_by: remplacé par
+concept.noChain: Aucune chaîne de succession enregistrée pour ce concept.
 
 # Sidebar
 sidebar.overview: Vue d'ensemble
@@ -185,3 +191,21 @@ dataset.alphabetical: Alphabétique
 dataset.sectionFilter: Section
 dataset.clearSection: Effacer la section
 dataset.conceptsInSection: concepts dans la section
+
+# Relation sphere view
+sphere.viewOptions: Options d'affichage
+sphere.degree: Degré
+sphere.language: Langue
+sphere.datasets: Jeux de données
+sphere.relationTypes: Types de relation
+sphere.expand: Expansion
+sphere.tight: serré
+sphere.loose: étendu
+sphere.redraw: Redessiner
+sphere.focus: FOCUS
+concept.detailView: Détail
+concept.relationSphere: Sphère de relations
+concept.permalink: Permalien
+concept.copied: Copié
+
+# Relation types (affichés dans la légende + étiquettes d'arêtes)

package/src/stores/vocabulary.ts

@@ -8,6 +8,7 @@ import { conceptUri } from '../adapters/model-bridge';
 import { GraphEngine } from '../graph';
 import { UriRouter } from '../adapters/UriRouter';
 import { deduplicateSearchHits } from '../utils/search';
+import { UnknownDatasetError } from '../errors';
 
 export const useVocabularyStore = defineStore('vocabulary', () => {
   // State
@@ -193,7 +194,7 @@ export const useVocabularyStore = defineStore('vocabulary', () => {
 
     try {
       const adapter = datasets.value.get(registerId);
-      if (!adapter) throw new Error(`Dataset ${registerId} not loaded`);
+      if (!adapter) throw UnknownDatasetError.make(registerId);
 
       // Fetch concept and cross-dataset edges in parallel
       const [concept] = await Promise.all([
@@ -332,6 +333,7 @@ export const useVocabularyStore = defineStore('vocabulary', () => {
     datasetList,
     discoverDatasets,
     loadDataset,
+    ensureEdgesForDataset,
     viewConcept,
     navigateToUri,
     searchAcrossDatasets,

package/src/style.css

@@ -482,10 +482,25 @@
 
 /* ── Sidebar group labels (brand colors are too dark in dark mode) ── */
 .dark .sidebar-group-label {
-  filter: brightness(2);
+  filter: brightness(1.6);
 }
 .dark .sidebar-group-label:hover {
-  filter: brightness(1.8);
+  filter: brightness(1.4);
+}
+
+/* ── Gold accent that adapts to theme ── */
+:root {
+  --gold-accent: #B8935A;
+  --gold-accent-deep: #8C6A3A;
+}
+.dark {
+  --gold-accent: #D4AF6E;
+  --gold-accent-deep: #B8935A;
+}
+
+/* Section labels brighter in dark mode */
+.dark .section-label {
+  color: theme('colors.ink.300') !important;
 }
 
 /* Scrollbar hide utility */

package/src/types/agents-version-turtle.d.ts

@@ -0,0 +1,27 @@
+declare module '*/scripts/lib/agents-turtle.mjs' {
+  export function buildAgentsTurtle(
+    contributors: readonly { name: string; role?: string; organization?: string; url?: string; email?: string }[],
+    agentBase?: string,
+  ): string;
+}
+
+declare module '*/scripts/lib/version-turtle.mjs' {
+  export interface VersionInput {
+    readonly registerId: string;
+    readonly version: string;
+    readonly versionIri: string;
+    readonly datasetIri: string;
+    readonly generatedAt: string;
+    readonly previousVersionIri?: string;
+    readonly changeSummary?: string;
+    readonly associatedAgentIri?: string;
+  }
+  export interface VersionHistoryInput {
+    readonly registerId: string;
+    readonly datasetIri: string;
+    readonly versions: readonly { version: string; generatedAt: string; changeSummary?: string }[];
+    readonly associatedAgentIri?: string;
+  }
+  export function buildVersionTurtle(input: VersionInput): string;
+  export function buildVersionHistoryTurtle(input: VersionHistoryInput): string;
+}

package/src/types/bibliography-turtle.d.ts

@@ -0,0 +1,12 @@
+declare module '*/scripts/lib/bibliography-turtle.mjs' {
+  export interface BibliographyEntryJson {
+    readonly reference?: string;
+    readonly title?: string;
+    readonly link?: string;
+  }
+  export function buildBibliographyTurtle(
+    register: string,
+    bibliographyJson: Record<string, BibliographyEntryJson>,
+    baseUri?: string,
+  ): string;
+}

package/src/types/build-activity-turtle.d.ts

@@ -0,0 +1,16 @@
+declare module '*/scripts/lib/build-activity-turtle.mjs' {
+  export interface BuildActivityTurtleInput {
+    readonly runId: string;
+    readonly startedAt: string;
+    readonly endedAt: string;
+    readonly gitSha?: string | null;
+    readonly gitBranch?: string | null;
+    readonly toolId: string;
+    readonly toolVersion: string;
+    readonly datasetRegisters: readonly string[];
+    readonly conceptCount: number;
+    readonly associatedAgentIri?: string | null;
+  }
+
+  export function buildActivityTurtle(input: BuildActivityTurtleInput): string;
+}

package/src/types/build-cache.d.ts

@@ -0,0 +1,20 @@
+declare module '*/scripts/lib/build-cache.mjs' {
+  export interface BuildCacheEntry<T = unknown> {
+    hash: string;
+    value: T;
+    storedAt: string;
+  }
+
+  export class BuildCache {
+    constructor(cacheDir: string);
+    get<T = unknown>(key: string): Promise<BuildCacheEntry<T> | null>;
+    set<T = unknown>(key: string, value: T, hash: string): Promise<void>;
+    readThrough<T>(
+      key: string,
+      hash: string,
+      producer: () => Promise<T>,
+    ): Promise<{ value: T; hit: boolean }>;
+    pathFor(key: string): string;
+    static hash(input: string): string;
+  }
+}

package/src/types/dataset-turtle.d.ts

@@ -0,0 +1,32 @@
+declare module '*/scripts/lib/dataset-turtle.mjs' {
+  export interface DatasetDistribution {
+    readonly id: string;
+    readonly title: string;
+    readonly mediaType: string;
+    readonly downloadUrl: string;
+    readonly byteSize?: number;
+  }
+
+  export interface DatasetSection {
+    readonly collectionIri: string;
+    readonly title: string;
+    readonly memberUris: readonly string[];
+  }
+
+  export interface DatasetTurtleInput {
+    readonly datasetIri: string;
+    readonly registerId: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly modified: string;
+    readonly languages: readonly string[];
+    readonly distributions: readonly DatasetDistribution[];
+    readonly topConceptUris: readonly string[];
+    readonly sections: readonly DatasetSection[];
+    readonly sourceRepoUrl?: string;
+    readonly publisherIri?: string;
+    readonly contactIri?: string;
+  }
+
+  export function buildDatasetTurtle(input: DatasetTurtleInput): string;
+}

package/src/types/normalize-yaml.d.ts

@@ -0,0 +1,16 @@
+declare module '*/scripts/normalize-yaml.mjs' {
+  export interface NormalizeResult {
+    checked: number;
+    nonNfc: number;
+    fixed: string[];
+    check: boolean;
+  }
+
+  export interface NormalizeOptions {
+    root?: string;
+    check?: boolean;
+    paths?: string[];
+  }
+
+  export function normalizeYaml(options?: NormalizeOptions): NormalizeResult;
+}

package/src/types/turtle-escape.d.ts

@@ -0,0 +1,6 @@
+declare module '*/scripts/lib/turtle-escape.mjs' {
+  export function ttlLit(s: unknown): string;
+  export function ttlPrefixed(qname: string): string;
+  export function ttlIri(iri: string): string;
+  export function assertValidIri(iri: unknown, context?: string): string;
+}

package/src/types/vocab-turtle.d.ts

@@ -0,0 +1,13 @@
+declare module '*/scripts/lib/vocab-turtle.mjs' {
+  export interface VocabTerm {
+    readonly iri: string;
+    readonly label: string;
+  }
+  export interface VocabScheme {
+    readonly schemeIri: string;
+    readonly label: string;
+    readonly terms: readonly VocabTerm[];
+  }
+  export function buildVocabularyTurtle(): string;
+  export function listVocabSchemes(): readonly VocabScheme[];
+}

package/src/utils/asciidoc-lite.ts

@@ -4,6 +4,7 @@
  */
 
 import { escapeHtml, escapeAttr } from './escape';
+import { sanitizeUrl } from './url-safety';
 
 export function renderAsciiDocLite(text: string): string {
   if (!text) return '';
@@ -102,14 +103,18 @@ export function renderAsciiDocLite(text: string): string {
 
 function inlineFormat(text: string): string {
   // AsciiDoc link: https://example.com[text]
-  text = text.replace(/(https?:\/\/[^\s\[]+)\[([^\]]*)\]/g, (_, url, label) =>
-    `<a href="${escapeHtml(url)}" target="_blank" rel="noopener">${escapeHtml(label || url)}</a>`
-  );
+  text = text.replace(/(https?:\/\/[^\s\[]+)\[([^\]]*)\]/g, (_, url, label) => {
+    const href = sanitizeUrl(url);
+    if (!href) return escapeHtml(label || url);
+    return `<a href="${escapeHtml(href)}" target="_blank" rel="noopener">${escapeHtml(label || url)}</a>`;
+  });
 
   // Bare URLs
-  text = text.replace(/(?<!href="|">)(https?:\/\/[^\s<]+)/g, url =>
-    `<a href="${escapeHtml(url)}" target="_blank" rel="noopener">${escapeHtml(url)}</a>`
-  );
+  text = text.replace(/(?<!href="|">)(https?:\/\/[^\s<]+)/g, url => {
+    const href = sanitizeUrl(url);
+    if (!href) return escapeHtml(url);
+    return `<a href="${escapeHtml(href)}" target="_blank" rel="noopener">${escapeHtml(url)}</a>`;
+  });
 
   // Monospace: `text`
   text = text.replace(/`([^`]+)`/g, '<code>$1</code>');

package/src/utils/bcp47.ts

@@ -0,0 +1,141 @@
+import { InvalidLangTagError } from '../errors';
+
+export interface LangTag {
+  readonly primary: string;
+  readonly script?: string;
+  readonly region?: string;
+  readonly variants?: string[];
+  readonly privateUse?: string[];
+  readonly raw: string;
+}
+
+const ISO_639_3_TO_1: Readonly<Record<string, string>> = {
+  eng: 'en', fra: 'fr', deu: 'de', zho: 'zh', ara: 'ar', jpn: 'ja', rus: 'ru',
+  kor: 'ko', spa: 'es', ita: 'it', por: 'pt', nld: 'nl', swe: 'sv', fin: 'fi',
+  dan: 'da', nob: 'nb', nno: 'nn', nor: 'no', pol: 'pl', tur: 'tr', ces: 'cs', ell: 'el',
+  heb: 'he', hin: 'hi', ind: 'id', fas: 'fa', ukr: 'uk', hun: 'hu', ron: 'ro',
+  slk: 'sk', slv: 'sl', hrv: 'hr', srp: 'sr', bul: 'bg', msa: 'ms', tha: 'th',
+  vie: 'vi', urd: 'ur', ben: 'bn', tam: 'ta', tel: 'te', mar: 'mr', guj: 'gu',
+  pan: 'pa', mal: 'ml', kan: 'kn', ori: 'or', asm: 'as', sin: 'si', nep: 'ne',
+  lit: 'lt', lav: 'lv', est: 'et', gle: 'ga', cym: 'cy', eus: 'eu', cat: 'ca',
+  glg: 'gl', afr: 'af', sqi: 'sq', mkd: 'mk', bel: 'be', kaz: 'kk', uzb: 'uz',
+  aze: 'az', hye: 'hy', kat: 'ka', mon: 'mn', tuk: 'tk', uig: 'ug', tgl: 'tl',
+};
+
+const ISO_639_1_TO_3: Readonly<Record<string, string>> = (() => {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(ISO_639_3_TO_1)) out[v] = k;
+  return Object.freeze(out);
+})();
+
+const DEFAULT_SCRIPTS: Readonly<Record<string, string>> = {
+  zh: 'Hans',
+  sr: 'Cyrl',
+  uz: 'Latn',
+};
+
+const SCRIPT_RE = /^[A-Z][a-z]{3}$/;
+const ISO_ALPHA2_REGION_RE = /^[A-Z]{2}$/;
+const UN_M49_REGION_RE = /^\d{3}$/;
+
+export function mapIso6393To6391(code: string): string | null {
+  return ISO_639_3_TO_1[code] ?? null;
+}
+
+export function mapIso6391To6393(code: string): string | null {
+  return ISO_639_1_TO_3[code] ?? null;
+}
+
+export function parseLangTag(input: string): LangTag {
+  if (!input || typeof input !== 'string') {
+    throw new InvalidLangTagError(`Invalid language tag: ${String(input)}`, { input });
+  }
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new InvalidLangTagError(`Empty language tag`, { input });
+  }
+
+  const segments = trimmed.split('-');
+  const first = segments[0]!;
+  if (!/^[a-zA-Z]{2,3}$/.test(first)) {
+    throw new InvalidLangTagError(
+      `Invalid primary subtag: ${first}`,
+      { input, subtag: first },
+    );
+  }
+
+  const primary = (ISO_639_3_TO_1[first.toLowerCase()] ?? first.toLowerCase());
+  const tag: LangTag = { primary, raw: input };
+
+  let i = 1;
+  let privateUse: string[] | undefined;
+  if (segments[i] === 'x') {
+    privateUse = segments.slice(i + 1);
+    i = segments.length;
+  }
+
+  let script: string | undefined;
+  let region: string | undefined;
+  let variants: string[] | undefined;
+
+  for (; i < segments.length; i++) {
+    const seg = segments[i]!;
+    if (seg === 'x') {
+      privateUse = segments.slice(i + 1);
+      break;
+    }
+    if (SCRIPT_RE.test(seg) && !script) {
+      script = seg;
+    } else if ((ISO_ALPHA2_REGION_RE.test(seg) || UN_M49_REGION_RE.test(seg)) && !region) {
+      region = seg;
+    } else if (/^[a-z0-9]{4,8}$/i.test(seg)) {
+      variants = variants ?? [];
+      variants.push(seg);
+    } else {
+      throw new InvalidLangTagError(
+        `Unrecognized language subtag: ${seg}`,
+        { input, subtag: seg },
+      );
+    }
+  }
+
+  const finalTag: LangTag = {
+    primary,
+    script: script ?? DEFAULT_SCRIPTS[primary],
+    region,
+    variants,
+    privateUse,
+    raw: input,
+  };
+  return finalTag;
+}
+
+export function formatLangTag(tag: LangTag): string {
+  const parts: string[] = [tag.primary];
+  if (tag.script) parts.push(tag.script);
+  if (tag.region) parts.push(tag.region);
+  if (tag.variants?.length) parts.push(...tag.variants);
+  if (tag.privateUse?.length) parts.push('x', ...tag.privateUse);
+  return parts.join('-');
+}
+
+export function canonicalLangTag(input: string): string {
+  return formatLangTag(parseLangTag(input));
+}
+
+export function isValidLangTag(input: string): boolean {
+  try {
+    parseLangTag(input);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isNfc(text: string): boolean {
+  return text.normalize('NFC') === text;
+}
+
+export function toNfc(text: string): string {
+  return text.normalize('NFC');
+}

package/src/utils/color-theme-integration.ts

@@ -0,0 +1,11 @@
+/**
+ * Color-theme integration bridge for the relationship-categories module.
+ * Re-exports the color pair accessors with a stable interface so consumers
+ * don't need to import from two places.
+ */
+export {
+  colorPairForType,
+  colorPairForCategory,
+  colorThemeForOverrides,
+} from './relationship-categories';
+export type { ColorPair } from './color-theme';