@glossarist/concept-browser 0.1.0

package/src/__tests__/dataset-style.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { makeDsStyle, paletteColor } from '../utils/dataset-style';
+
+describe('makeDsStyle', () => {
+  it('returns color, light, and dark variants', () => {
+    const style = makeDsStyle('#3366ff');
+    expect(style.color).toBe('#3366ff');
+    expect(style.light).toMatch(/^rgba\(51, 102, 255, 0\.1\)$/);
+    expect(style.dark).toMatch(/^rgba\(51, 102, 255, 0\.85\)$/);
+  });
+
+  it('light variant has alpha 0.1', () => {
+    const style = makeDsStyle('#d97706');
+    expect(style.light).toContain('0.1)');
+  });
+
+  it('dark variant has alpha 0.85', () => {
+    const style = makeDsStyle('#d97706');
+    expect(style.dark).toContain('0.85)');
+  });
+});
+
+describe('paletteColor', () => {
+  it('returns correct color for index 0', () => {
+    expect(paletteColor(0)).toBe('#3366ff');
+  });
+
+  it('returns correct color for index 3', () => {
+    expect(paletteColor(3)).toBe('#8b5cf6');
+  });
+
+  it('cycles through palette for indices beyond length', () => {
+    // Palette has 12 entries (indices 0-11), so index 12 wraps to 0
+    expect(paletteColor(12)).toBe(paletteColor(0));
+    expect(paletteColor(13)).toBe(paletteColor(1));
+  });
+});

package/src/__tests__/graph.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect } from 'vitest';
+import { GraphEngine } from '../graph/GraphEngine';
+import type { GraphNode, GraphEdge } from '../adapters/types';
+
+function makeNode(uri: string, conceptId: string, register = 'test', overrides?: Partial<GraphNode>): GraphNode {
+  return {
+    uri,
+    register,
+    conceptId,
+    designations: { eng: conceptId },
+    status: 'valid',
+    loaded: true,
+    ...overrides,
+  };
+}
+
+function makeEdge(source: string, target: string, type = 'references', register = 'test'): GraphEdge {
+  return { source, target, type, register };
+}
+
+describe('GraphEngine', () => {
+  it('starts empty', () => {
+    const g = new GraphEngine();
+    expect(g.nodeCount).toBe(0);
+    expect(g.edgeCount).toBe(0);
+    expect(g.getAllNodes()).toEqual([]);
+    expect(g.getEdges()).toEqual([]);
+  });
+
+  describe('addNode', () => {
+    it('adds a node that can be retrieved', () => {
+      const g = new GraphEngine();
+      const node = makeNode('uri:a', 'a');
+      g.addNode(node);
+      expect(g.nodeCount).toBe(1);
+      expect(g.getNode('uri:a')).toEqual(node);
+    });
+
+    it('does not duplicate nodes with the same URI', () => {
+      const g = new GraphEngine();
+      g.addNode(makeNode('uri:a', 'a'));
+      g.addNode(makeNode('uri:a', 'a-updated'));
+      expect(g.nodeCount).toBe(1);
+      // Original node is kept (not overwritten)
+      expect(g.getNode('uri:a')?.conceptId).toBe('a');
+    });
+  });
+
+  describe('addEdge', () => {
+    it('creates stub nodes for unknown source/target', () => {
+      const g = new GraphEngine();
+      g.addEdge(makeEdge('uri:a', 'uri:b'));
+      expect(g.nodeCount).toBe(2);
+      expect(g.getNode('uri:a')?.loaded).toBe(false);
+      expect(g.getNode('uri:a')?.status).toBe('stub');
+      expect(g.getNode('uri:b')?.status).toBe('stub');
+      expect(g.edgeCount).toBe(1);
+    });
+
+    it('does not overwrite existing nodes with stubs', () => {
+      const g = new GraphEngine();
+      g.addNode(makeNode('uri:a', 'a', 'test', { loaded: true, status: 'valid' }));
+      g.addEdge(makeEdge('uri:a', 'uri:b'));
+      expect(g.getNode('uri:a')?.loaded).toBe(true);
+      expect(g.getNode('uri:a')?.status).toBe('valid');
+    });
+
+    it('upgrades stub node when loaded node is added', () => {
+      const g = new GraphEngine();
+      g.addEdge(makeEdge('uri:a', 'uri:b'));
+      expect(g.getNode('uri:a')?.loaded).toBe(false);
+      g.addNode(makeNode('uri:a', 'a', 'test', { loaded: true, status: 'valid' }));
+      expect(g.getNode('uri:a')?.loaded).toBe(true);
+      expect(g.getNode('uri:a')?.conceptId).toBe('a');
+    });
+
+    it('supports multiple edges between same pair', () => {
+      const g = new GraphEngine();
+      g.addEdge(makeEdge('uri:a', 'uri:b', 'references'));
+      g.addEdge(makeEdge('uri:a', 'uri:b', 'related'));
+      expect(g.edgeCount).toBe(2);
+      const edges = g.getEdges('uri:a');
+      expect(edges.length).toBe(2);
+      expect(edges.map(e => e.type).sort()).toEqual(['references', 'related']);
+    });
+
+    it('deduplicates identical edges', () => {
+      const g = new GraphEngine();
+      g.addEdge(makeEdge('uri:a', 'uri:b', 'references'));
+      g.addEdge(makeEdge('uri:a', 'uri:b', 'references'));
+      expect(g.edgeCount).toBe(1);
+    });
+
+    it('extracts register from URI for stub nodes', () => {
+      const g = new GraphEngine();
+      g.addEdge({
+        source: 'https://glossarist.org/isotc204/concept/3.1.1.1',
+        target: 'https://glossarist.org/iev/concept/102-01-10',
+        type: 'references',
+        register: 'isotc204',
+      });
+      const target = g.getNode('https://glossarist.org/iev/concept/102-01-10');
+      expect(target?.register).toBe('iev');
+      expect(target?.conceptId).toBe('102-01-10');
+    });
+  });
+
+  describe('getNeighbors', () => {
+    it('returns outgoing and incoming neighbors', () => {
+      const g = new GraphEngine();
+      g.addNode(makeNode('uri:a', 'a'));
+      g.addNode(makeNode('uri:b', 'b'));
+      g.addNode(makeNode('uri:c', 'c'));
+      g.addEdge(makeEdge('uri:a', 'uri:b'));
+      g.addEdge(makeEdge('uri:c', 'uri:a'));
+
+      const neighbors = g.getNeighbors('uri:a');
+      expect(neighbors.outgoing).toEqual(['uri:b']);
+      expect(neighbors.incoming).toEqual(['uri:c']);
+    });
+
+    it('returns empty arrays for unknown nodes', () => {
+      const g = new GraphEngine();
+      const n = g.getNeighbors('uri:unknown');
+      expect(n.outgoing).toEqual([]);
+      expect(n.incoming).toEqual([]);
+    });
+  });
+
+  describe('getIncomingEdges', () => {
+    it('returns edges pointing to a node', () => {
+      const g = new GraphEngine();
+      g.addEdge(makeEdge('uri:a', 'uri:c'));
+      g.addEdge(makeEdge('uri:b', 'uri:c'));
+      g.addEdge(makeEdge('uri:c', 'uri:d'));
+
+      const incoming = g.getIncomingEdges('uri:c');
+      expect(incoming.length).toBe(2);
+      expect(incoming.map(e => e.source).sort()).toEqual(['uri:a', 'uri:b']);
+    });
+  });
+
+  describe('getSubgraph', () => {
+    it('returns a BFS subgraph of given depth', () => {
+      const g = new GraphEngine();
+      g.addNode(makeNode('uri:a', 'a'));
+      g.addNode(makeNode('uri:b', 'b'));
+      g.addNode(makeNode('uri:c', 'c'));
+      g.addNode(makeNode('uri:d', 'd'));
+      g.addEdge(makeEdge('uri:a', 'uri:b'));
+      g.addEdge(makeEdge('uri:b', 'uri:c'));
+      g.addEdge(makeEdge('uri:c', 'uri:d'));
+
+      const sub = g.getSubgraph('uri:a', 1);
+      expect(sub.nodes.length).toBe(2); // a, b
+      // Edges touching collected nodes: a->b is outgoing, plus any incoming to a or b
+      // b->c is an outgoing edge of b, collected because b is a collected node
+      expect(sub.edges.length).toBeGreaterThanOrEqual(1);
+      expect(sub.edges.some(e => e.source === 'uri:a' && e.target === 'uri:b')).toBe(true);
+
+      const sub2 = g.getSubgraph('uri:a', 2);
+      expect(sub2.nodes.length).toBe(3); // a, b, c
+    });
+
+    it('does not loop infinitely on cycles', () => {
+      const g = new GraphEngine();
+      g.addNode(makeNode('uri:a', 'a'));
+      g.addNode(makeNode('uri:b', 'b'));
+      g.addEdge(makeEdge('uri:a', 'uri:b'));
+      g.addEdge(makeEdge('uri:b', 'uri:a'));
+
+      const sub = g.getSubgraph('uri:a', 5);
+      expect(sub.nodes.length).toBe(2);
+    });
+  });
+
+  describe('getAllNodes', () => {
+    it('returns all nodes', () => {
+      const g = new GraphEngine();
+      g.addNode(makeNode('uri:a', 'a'));
+      g.addNode(makeNode('uri:b', 'b'));
+      const all = g.getAllNodes();
+      expect(all.length).toBe(2);
+      expect(all.map(n => n.conceptId).sort()).toEqual(['a', 'b']);
+    });
+  });
+});

package/src/__tests__/lang.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { langName, langLabel, DEFAULT_LANG } from '../utils/lang';
+
+describe('langName', () => {
+  it('returns name for known codes', () => {
+    expect(langName('eng')).toBe('English');
+    expect(langName('fra')).toBe('French');
+    expect(langName('deu')).toBe('German');
+    expect(langName('zho')).toBe('Chinese');
+  });
+
+  it('returns code as-is for unknown codes', () => {
+    expect(langName('xyz')).toBe('xyz');
+    expect(langName('abc')).toBe('abc');
+  });
+});
+
+describe('langLabel', () => {
+  it('uppercases the code', () => {
+    expect(langLabel('eng')).toBe('ENG');
+    expect(langLabel('fra')).toBe('FRA');
+  });
+});
+
+describe('DEFAULT_LANG', () => {
+  it('is eng', () => {
+    expect(DEFAULT_LANG).toBe('eng');
+  });
+});

package/src/__tests__/math.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest';
+import { renderMath, cleanContent } from '../utils/math';
+
+describe('renderMath', () => {
+  it('passes through plain text unchanged', () => {
+    expect(renderMath('hello world')).toBe('hello world');
+  });
+
+  it('renders stem:[x^2] to KaTeX span', () => {
+    const result = renderMath('the value stem:[x^2]');
+    expect(result).toContain('math-inline');
+    expect(result).toContain('katex');
+    expect(result).not.toContain('math-bold');
+  });
+
+  it('renders *stem:[x]* (bold math) with math-bold class', () => {
+    const result = renderMath('the value *stem:[x]*');
+    expect(result).toContain('math-inline');
+    expect(result).toContain('math-bold');
+  });
+
+  it('converts bullet lines to <ul><li>', () => {
+    const result = renderMath('* first item\n\n* second item');
+    expect(result).toContain('<ul class="concept-list">');
+    expect(result).toContain('<li>first item</li>');
+    expect(result).toContain('<li>second item</li>');
+  });
+
+  it('does NOT convert *stem:[...] lines to list items', () => {
+    const result = renderMath('*stem:[x]*');
+    expect(result).not.toContain('<ul');
+    expect(result).toContain('math-bold');
+  });
+
+  it('converts *text* to <em> (italic)', () => {
+    expect(renderMath('some *italic* text')).toBe('some <em>italic</em> text');
+  });
+
+  it('converts ~text~ to <sub> (subscript)', () => {
+    expect(renderMath('H~2~O')).toBe('H<sub>2</sub>O');
+  });
+
+  it('resolves URN inline refs via xrefResolver', () => {
+    const resolver = (uri: string, term: string) => `[${term}→${uri}]`;
+    const result = renderMath(
+      'a {{urn:iso:std:iso:14812:3.1.1.1,entity}} reference',
+      resolver,
+    );
+    expect(result).toBe('a [entity→urn:iso:std:iso:14812:3.1.1.1] reference');
+  });
+
+  it('resolves single-braced URN inline refs', () => {
+    const resolver = (uri: string, term: string) => `[${term}→${uri}]`;
+    const result = renderMath(
+      'a {urn:iso:std:iso:14812:3.1.1.1,entity} reference',
+      resolver,
+    );
+    expect(result).toBe('a [entity→urn:iso:std:iso:14812:3.1.1.1] reference');
+  });
+
+  it('shows term without resolver', () => {
+    const result = renderMath('a {{urn:iso:std:iso:14812:3.1.1.1,entity}} ref');
+    expect(result).toBe('a entity ref');
+  });
+
+  it('strips remaining {{...}} to just the term', () => {
+    const result = renderMath('see {{some term, unknown ref}}');
+    expect(result).toBe('see some term');
+  });
+
+  it('handles empty input', () => {
+    expect(renderMath('')).toBe('');
+  });
+
+  it('handles null-ish input', () => {
+    expect(renderMath(null as any)).toBe('');
+    expect(renderMath(undefined as any)).toBe('');
+  });
+});
+
+describe('cleanContent', () => {
+  it('strips stem:[...] to raw math text', () => {
+    expect(cleanContent('value stem:[x^2] here')).toBe('value x^2 here');
+  });
+
+  it('strips bold stem', () => {
+    expect(cleanContent('value *stem:[x]* here')).toBe('value x here');
+  });
+
+  it('strips *text* to plain text', () => {
+    expect(cleanContent('some *italic* text')).toBe('some italic text');
+  });
+
+  it('converts ~text~ to _text', () => {
+    expect(cleanContent('H~2~O')).toBe('H_2O');
+  });
+
+  it('strips list markers', () => {
+    const result = cleanContent('items:\n* one\n* two');
+    expect(result).toContain('one');
+    expect(result).toContain('two');
+    expect(result).not.toContain('* ');
+  });
+
+  it('strips URN refs to just the term', () => {
+    expect(cleanContent('a {{urn:iso:std:iso:14812:3.1.1.1,entity}} ref')).toBe('a entity ref');
+  });
+
+  it('handles empty input', () => {
+    expect(cleanContent('')).toBe('');
+    expect(cleanContent(null as any)).toBe('');
+  });
+});

package/src/__tests__/reference-resolver.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ReferenceResolver } from '../adapters/ReferenceResolver';
+
+describe('ReferenceResolver', () => {
+  let resolver: ReferenceResolver;
+
+  beforeEach(() => {
+    resolver = new ReferenceResolver();
+  });
+
+  describe('resolveReference', () => {
+    it('resolves internal URI for provided dataset', () => {
+      resolver.registerDataset('isotc204', ['urn:iso:std:iso:14812:*', 'https://glossarist.org/isotc204/*']);
+      const result = resolver.resolveReference('https://glossarist.org/isotc204/concept/3.1.1.1');
+      expect(result).toEqual({
+        type: 'internal',
+        registerId: 'isotc204',
+        conceptId: '3.1.1.1',
+        crossDataset: false,
+      });
+    });
+
+    it('resolves URN to internal for provided dataset', () => {
+      resolver.registerDataset('isotc204', ['urn:iso:std:iso:14812:*']);
+      const result = resolver.resolveReference('urn:iso:std:iso:14812:3.1.1.1');
+      expect(result).toEqual({
+        type: 'internal',
+        registerId: 'isotc204',
+        conceptId: '3.1.1.1',
+        crossDataset: false,
+      });
+    });
+
+    it('sets crossDataset=true when source dataset differs', () => {
+      resolver.registerDataset('iev', ['urn:iec:std:iec:60050:*']);
+      resolver.registerDataset('isotc204', ['urn:iso:std:iso:14812:*']);
+      const result = resolver.resolveReference('urn:iec:std:iec:60050:103-01-02', 'isotc204');
+      expect(result).toEqual({
+        type: 'internal',
+        registerId: 'iev',
+        conceptId: '103-01-02',
+        crossDataset: true,
+      });
+    });
+
+    it('resolves to site via routing table', () => {
+      resolver.loadRouting([
+        {
+          uri: 'https://glossarist.org/iev/*',
+          type: 'site',
+          baseUrl: 'https://www.geolexica.org',
+          label: 'Geolexica Hub',
+        },
+      ]);
+      const result = resolver.resolveReference('https://glossarist.org/iev/concept/103-01-02');
+      expect(result).toEqual({
+        type: 'site',
+        baseUrl: 'https://www.geolexica.org',
+        conceptUri: 'https://glossarist.org/iev/concept/103-01-02',
+        label: 'Geolexica Hub',
+      });
+    });
+
+    it('resolves to url via routing table with {conceptId} substitution', () => {
+      resolver.loadRouting([
+        {
+          uri: 'urn:iec:std:iec:60050:*',
+          type: 'url',
+          url: 'https://electropedia.org/iev/iev.nsf/display?openform&ievref={conceptId}',
+          label: 'IEC Electropedia',
+        },
+      ]);
+      const result = resolver.resolveReference('urn:iec:std:iec:60050:103-01-02');
+      expect(result).toEqual({
+        type: 'url',
+        url: 'https://electropedia.org/iev/iev.nsf/display?openform&ievref=103-01-02',
+        label: 'IEC Electropedia',
+      });
+    });
+
+    it('resolves to url without conceptId placeholder', () => {
+      resolver.loadRouting([
+        {
+          uri: 'https://glossarist.org/legacy/*',
+          type: 'url',
+          url: 'https://example.com/obp/concepts',
+          label: 'Legacy concepts',
+        },
+      ]);
+      const result = resolver.resolveReference('https://glossarist.org/legacy/concept/123');
+      expect(result).toEqual({
+        type: 'url',
+        url: 'https://example.com/obp/concepts',
+        label: 'Legacy concepts',
+      });
+    });
+
+    it('prefers provided dataset over routing', () => {
+      resolver.registerDataset('iev', ['urn:iec:std:iec:60050:*']);
+      resolver.loadRouting([
+        {
+          uri: 'urn:iec:std:iec:60050:*',
+          type: 'url',
+          url: 'https://electropedia.org/{conceptId}',
+          label: 'External',
+        },
+      ]);
+      const result = resolver.resolveReference('urn:iec:std:iec:60050:103-01-02');
+      expect(result.type).toBe('internal');
+    });
+
+    it('returns unresolved for unknown URIs', () => {
+      const result = resolver.resolveReference('https://glossarist.org/unknown/concept/123');
+      expect(result).toEqual({ type: 'unresolved', uri: 'https://glossarist.org/unknown/concept/123' });
+    });
+
+    it('returns unresolved for non-matching URNs', () => {
+      const result = resolver.resolveReference('urn:other:scheme:123');
+      expect(result).toEqual({ type: 'unresolved', uri: 'urn:other:scheme:123' });
+    });
+  });
+});

package/src/__tests__/site-config.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import type { RuntimeSiteConfig } from '../config/use-site-config';
+
+describe('RuntimeSiteConfig', () => {
+  it('accepts valid config structure', () => {
+    const config: RuntimeSiteConfig = {
+      id: 'geolexica',
+      domain: 'www.geolexica.org',
+      title: 'Geolexica',
+      datasets: ['iev', 'isotc211', 'isotc204', 'osgeo'],
+      branding: { primaryColor: '#2563eb' },
+      defaults: { language: 'eng' },
+    };
+    expect(config.datasets).toEqual(['iev', 'isotc211', 'isotc204', 'osgeo']);
+    expect(config.branding?.primaryColor).toBe('#2563eb');
+  });
+
+  it('supports single-dataset config', () => {
+    const config: RuntimeSiteConfig = {
+      id: 'isotc204',
+      domain: 'isotc204.geolexica.org',
+      title: 'ISO/TC 204 ITS Vocabulary',
+      datasets: ['isotc204'],
+      defaultDataset: 'isotc204',
+      branding: { primaryColor: '#d97706', ownerName: 'ISO/TC 204' },
+      defaults: { language: 'eng' },
+    };
+    expect(config.datasets).toEqual(['isotc204']);
+    expect(config.defaultDataset).toBe('isotc204');
+  });
+
+  it('supports optional fields', () => {
+    const config: RuntimeSiteConfig = {
+      id: 'osgeo',
+      domain: 'osgeo.geolexica.org',
+      title: 'OSGeo Lexicon',
+      subtitle: 'Open Source Geospatial Glossary',
+      datasets: ['osgeo'],
+      branding: {
+        primaryColor: '#059669',
+        ownerName: 'OSGeo',
+        ownerUrl: 'https://www.osgeo.org',
+      },
+      analytics: { googleAnalyticsId: 'UA-168998071-3' },
+      features: { graph: true, search: true },
+      social: { github: 'https://github.com/geolexica/osgeo-glossary' },
+      defaults: { language: 'eng' },
+    };
+    expect(config.subtitle).toBe('Open Source Geospatial Glossary');
+    expect(config.analytics?.googleAnalyticsId).toBe('UA-168998071-3');
+  });
+});

package/src/__tests__/uri-router.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { UriRouter } from '../adapters/UriRouter';
+
+describe('UriRouter', () => {
+  it('resolves URIs for registered datasets', () => {
+    const router = new UriRouter();
+    router.registerDataset('iev', '/data/iev');
+
+    const resolved = router.resolveUri('https://glossarist.org/iev/concept/103-01-02');
+    expect(resolved).toEqual({ registerId: 'iev', conceptId: '103-01-02' });
+  });
+
+  it('resolves URIs with multi-part concept IDs', () => {
+    const router = new UriRouter();
+    router.registerDataset('isotc204', '/data/isotc204');
+
+    const resolved = router.resolveUri('https://glossarist.org/isotc204/concept/3.1.1.1');
+    expect(resolved).toEqual({ registerId: 'isotc204', conceptId: '3.1.1.1' });
+  });
+
+  it('returns null for unknown register', () => {
+    const router = new UriRouter();
+    router.registerDataset('iev', '/data/iev');
+
+    expect(router.resolveUri('https://glossarist.org/unknown/concept/123')).toBeNull();
+  });
+
+  it('returns null for non-matching URI pattern', () => {
+    const router = new UriRouter();
+    router.registerDataset('iev', '/data/iev');
+
+    expect(router.resolveUri('https://example.com/other')).toBeNull();
+  });
+
+  it('builds URIs from register and concept ID', () => {
+    const router = new UriRouter();
+    expect(router.buildUri('iev', '103-01-02')).toBe('https://glossarist.org/iev/concept/103-01-02');
+  });
+
+  it('lists all registered IDs', () => {
+    const router = new UriRouter();
+    router.registerDataset('iev', '/data/iev');
+    router.registerDataset('isotc211', '/data/isotc211');
+
+    expect(router.getRegisteredIds()).toEqual(['iev', 'isotc211']);
+  });
+
+  it('resolves across multiple registers', () => {
+    const router = new UriRouter();
+    router.registerDataset('iev', '/data/iev');
+    router.registerDataset('isotc211', '/data/isotc211');
+    router.registerDataset('isotc204', '/data/isotc204');
+
+    expect(router.resolveUri('https://glossarist.org/iev/concept/102-01-01')?.registerId).toBe('iev');
+    expect(router.resolveUri('https://glossarist.org/isotc211/concept/10')?.registerId).toBe('isotc211');
+    expect(router.resolveUri('https://glossarist.org/isotc204/concept/3.1.1.1')?.registerId).toBe('isotc204');
+  });
+
+  describe('parseUri (static)', () => {
+    it('extracts register and concept from any glossarist URI', () => {
+      expect(UriRouter.parseUri('https://glossarist.org/iev/concept/103-01-02')).toEqual({
+        registerId: 'iev', conceptId: '103-01-02',
+      });
+    });
+
+    it('handles multi-part concept IDs', () => {
+      expect(UriRouter.parseUri('https://glossarist.org/isotc204/concept/3.1.1.1')).toEqual({
+        registerId: 'isotc204', conceptId: '3.1.1.1',
+      });
+    });
+
+    it('returns null for non-matching URIs', () => {
+      expect(UriRouter.parseUri('https://example.com/other')).toBeNull();
+    });
+  });
+});