@glossarist/concept-browser 0.7.94 → 0.7.96

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.94",
+  "version": "0.7.96",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {

package/scripts/generate-data.mjs

@@ -91,6 +91,7 @@ function loadConceptFile(filePath) {
     // Managed concept-level fields
     if (mc.related) result._related = mc.related;
     if (mc.partitive_relations) result._partitiveRelations = mc.partitive_relations;
+    if (mc.generic_relations) result._genericRelations = mc.generic_relations;
     if (mc.data.domains) result._domains = mc.data.domains;
     if (mc.dates) result._dates = mc.dates;
     if (mc.sources) result._sources = mc.sources;
@@ -769,6 +770,54 @@ function yamlToJsonLd(conceptYaml, register, refMaps) {
     });
   }
 
+  if (conceptYaml._genericRelations?.length > 0) {
+    doc['gl:genericRelations'] = conceptYaml._genericRelations.map(rel => {
+      const out = { '@type': 'gl:GenericRelation' };
+      if (rel.comprehensive) {
+        out['gl:comprehensive'] = refToJsonLd(rel.comprehensive, 'gl:ConceptRef');
+      }
+      if (Array.isArray(rel.members) && rel.members.length > 0) {
+        out['gl:hasGeneric'] = rel.members.map(member => {
+          const m = { '@type': 'gl:GenericMember' };
+          if (member.ref) {
+            m['gl:ref'] = refToJsonLd(member.ref, 'gl:ConceptRef');
+          } else {
+            m['gl:ref'] = refToJsonLd(member, 'gl:ConceptRef');
+          }
+          const presence = member.presence
+            ?? splitMultiplicity(member.multiplicity ?? '').presence;
+          const count = member.count
+            ?? splitMultiplicity(member.multiplicity ?? '').count;
+          m['gl:presence'] = presence;
+          m['gl:count'] = count;
+          /* ISO 704:2022 §5.5.4.2.1 — every generic member carries a
+             delimiting characteristic that distinguishes it from its
+             coordinate concepts. Required field. */
+          if (member.delimiting_characteristic || member.delimitingCharacteristic) {
+            const dc = member.delimiting_characteristic ?? member.delimitingCharacteristic;
+            m['gl:delimitingCharacteristic'] = typeof dc === 'string'
+              ? { default: dc }
+              : dc;
+          }
+          if (member.multiplicity) m['gl:multiplicity'] = member.multiplicity;
+          const legacyCertainty = member.certainty
+            ?? LEGACY_CERTAINTY_FROM_AXIS[presence];
+          if (legacyCertainty) m['gl:certainty'] = legacyCertainty;
+          return m;
+        });
+      }
+      if (rel.completeness) {
+        out['gl:completeness'] = rel.completeness;
+      }
+      if (rel.criterion) {
+        out['gl:criterion'] = typeof rel.criterion === 'string'
+          ? { default: rel.criterion }
+          : rel.criterion;
+      }
+      return out;
+    });
+  }
+
   return doc;
 }
 

package/src/__tests__/__fixtures__/concepts.ts

@@ -233,6 +233,36 @@ function withPartitiveHyperedge(): Concept {
   });
 }
 
+function withGenericHyperedge(): Concept {
+  const source = 'urn:glossarist:fixtures';
+  return Concept.fromJSON({
+    id: '1.9',
+    uri: `${BASE}/with-generic-hyperedge`,
+    status: 'valid',
+    localizations: {
+      eng: {
+        language_code: 'eng',
+        entry_status: 'valid',
+        terms: [{ type: 'expression', designation: 'measurement unit', normative_status: 'preferred' }],
+        definition: [{ content: 'A concept that has a generic (genus/species) decomposition.' }],
+      },
+    },
+    relations: [
+      {
+        type: 'generic_relation',
+        comprehensive: { source, id: '1.9' },
+        criterion: { eng: 'by magnitude relationship to a reference unit' },
+        members: [
+          { ref: { source, id: '1.17' }, presence: 'required', count: 'at_least_one', delimitingCharacteristic: { eng: 'multiple of a unit' } },
+          { ref: { source, id: '1.18' }, presence: 'required', count: 'at_least_one', delimitingCharacteristic: { eng: 'submultiple of a unit' } },
+          { ref: { source, id: '1.12' }, presence: 'required', count: 'at_least_one', delimitingCharacteristic: { eng: 'coherent derived unit' } },
+        ],
+        completeness: 'partial',
+      },
+    ],
+  });
+}
+
 export const CONCEPT_FIXTURES: readonly ConceptFixture[] = [
   { name: 'minimal',            description: 'one localization, one designation',                uri: `${BASE}/minimal`,            concept: minimal() },
   { name: 'multilingual',       description: 'three languages across Latn and CJK scripts',      uri: `${BASE}/multilingual`,       concept: multilingual() },
@@ -242,6 +272,7 @@ export const CONCEPT_FIXTURES: readonly ConceptFixture[] = [
   { name: 'with-dates',         description: 'accepted/amended/retired lifecycle',               uri: `${BASE}/with-dates`,         concept: withDates() },
   { name: 'withdrawn',          description: 'withdrawn status with retirement date (J3)',        uri: `${BASE}/withdrawn`,          concept: withdrawnConcept() },
   { name: 'with-partitive-hyperedge', description: 'partitive decomposition in concept.relations', uri: `${BASE}/with-partitive-hyperedge`, concept: withPartitiveHyperedge() },
+  { name: 'with-generic-hyperedge',   description: 'generic (genus/species) decomposition in concept.relations', uri: `${BASE}/with-generic-hyperedge`, concept: withGenericHyperedge() },
 ];
 
 export function fixtureByName(name: string): ConceptFixture {

package/src/__tests__/composables/use-concept-edges-hyperedge.test.ts

@@ -112,4 +112,32 @@ describe('useConceptEdges — hyperedge projection (regression)', () => {
     );
     expect(conceptPartitiveRelations.value.length).toBe(1);
   });
+
+  it('projects a GenericHyperedge from concept.relations', () => {
+    const { concept } = fixtureByName('with-generic-hyperedge');
+    const { conceptGenericRelations } = useConceptEdges(
+      computed(() => concept),
+      computed(() => 'fixtures'),
+      computed(() => manifest),
+      computed(() => noEdges),
+      noopRouter,
+    );
+
+    const rels = conceptGenericRelations.value;
+    expect(rels).toHaveLength(1);
+
+    const [rel] = rels;
+    expect(rel.comprehensive).toBe('https://glossarist.org/fixtures/concept/1.9');
+    expect(rel.members).toHaveLength(3);
+    expect(rel.members.map(m => m.uri)).toEqual([
+      'https://glossarist.org/fixtures/concept/1.17',
+      'https://glossarist.org/fixtures/concept/1.18',
+      'https://glossarist.org/fixtures/concept/1.12',
+    ]);
+    /* ISO 704:2022 §5.5.4.2.1 — every generic member carries a
+       delimiting characteristic. Pin the field is projected. */
+    expect(rel.members[0].delimitingCharacteristic).toEqual({ eng: 'multiple of a unit' });
+    expect(rel.members[1].delimitingCharacteristic).toEqual({ eng: 'submultiple of a unit' });
+    expect(rel.criterion).toEqual({ eng: 'by magnitude relationship to a reference unit' });
+  });
 });

package/src/__tests__/sphere-math.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { hashSeed, expandParams, portSide, portPoint, idToUriGet } from '../utils/sphere-math';
+import { hashSeed, expandParams, portSide, portPoint, idToUriGet, visibleNodeIds } from '../utils/sphere-math';
+import type { SphereHyperedgeLike } from '../utils/sphere-math';
 
 describe('sphere-math', () => {
   describe('hashSeed', () => {
@@ -53,4 +54,135 @@ describe('sphere-math', () => {
       expect(idToUriGet(map, '/uri/unknown')).toBeUndefined();
     });
   });
+
+  describe('visibleNodeIds', () => {
+    const focus = { id: 'focus', register: 'main', depth: 0 };
+    const a = { id: 'a', register: 'main', depth: 1 };
+    const b = { id: 'b', register: 'main', depth: 1 };
+    const c = { id: 'c', register: 'main', depth: 1 };
+    const d = { id: 'd', register: 'other', depth: 1 };
+
+    const buildLinks = (links: Array<[string, string, string]>) =>
+      links.map(([source, target, type]) => ({ source, target, type }));
+
+    it('always includes the focus node (depth 0)', () => {
+      const nodes = [focus, a];
+      const links = buildLinks([['focus', 'a', 'related']]);
+      const visible = visibleNodeIds(nodes, links, new Set(), new Set());
+      expect(visible.has('focus')).toBe(true);
+    });
+
+    it('includes a node that has at least one non-muted edge', () => {
+      const nodes = [focus, a, b];
+      const links = buildLinks([
+        ['focus', 'a', 'related'],
+        ['focus', 'b', 'see'],
+      ]);
+      const visible = visibleNodeIds(nodes, links, new Set(), new Set());
+      expect(visible.has('a')).toBe(true);
+      expect(visible.has('b')).toBe(true);
+    });
+
+    it('hides a node whose only edge type is muted', () => {
+      const nodes = [focus, a, b];
+      const links = buildLinks([
+        ['focus', 'a', 'related'],
+        ['focus', 'b', 'see'],
+      ]);
+      const visible = visibleNodeIds(nodes, links, new Set(['see']), new Set());
+      expect(visible.has('a')).toBe(true);
+      expect(visible.has('b')).toBe(false);
+    });
+
+    it('vice versa: hidden node reappears when type is unmuted', () => {
+      const nodes = [focus, a, b];
+      const links = buildLinks([
+        ['focus', 'a', 'related'],
+        ['focus', 'b', 'see'],
+      ]);
+      const muted = new Set(['see']);
+      expect(visibleNodeIds(nodes, links, muted, new Set()).has('b')).toBe(false);
+      muted.delete('see');
+      expect(visibleNodeIds(nodes, links, muted, new Set()).has('b')).toBe(true);
+    });
+
+    it('keeps a node visible if it has at least one unmuted edge among several', () => {
+      const nodes = [focus, a, b, c];
+      const links = buildLinks([
+        ['focus', 'a', 'related'],
+        ['focus', 'a', 'see'],
+        ['focus', 'b', 'see'],
+        ['focus', 'c', 'related'],
+      ]);
+      const visible = visibleNodeIds(nodes, links, new Set(['see']), new Set());
+      expect(visible.has('a')).toBe(true);
+      expect(visible.has('b')).toBe(false);
+      expect(visible.has('c')).toBe(true);
+    });
+
+    it('hides a node in a muted register (unless it is the focus)', () => {
+      const nodes = [focus, a, d];
+      const links = buildLinks([
+        ['focus', 'a', 'related'],
+        ['focus', 'd', 'related'],
+      ]);
+      const visible = visibleNodeIds(nodes, links, new Set(), new Set(['other']));
+      expect(visible.has('a')).toBe(true);
+      expect(visible.has('d')).toBe(false);
+    });
+
+    it('hides a node whose only edge endpoint is in a muted register', () => {
+      const nodes = [focus, a, d];
+      const links = buildLinks([
+        ['a', 'd', 'related'],
+      ]);
+      const visible = visibleNodeIds(nodes, links, new Set(), new Set(['other']));
+      expect(visible.has('a')).toBe(false);
+      expect(visible.has('d')).toBe(false);
+    });
+
+    it('isolated non-focus node (no edges at all) is hidden', () => {
+      const nodes = [focus, a];
+      const links: Array<{ source: string; target: string; type: string }> = [];
+      const visible = visibleNodeIds(nodes, links, new Set(), new Set());
+      expect(visible.has('focus')).toBe(true);
+      expect(visible.has('a')).toBe(false);
+    });
+
+    it('hyperedge member with no bilateral edges stays visible while its bundle is not muted', () => {
+      const nodes = [focus, a, b];
+      const links: Array<{ source: string; target: string; type: string }> = [];
+      const hyperedges: SphereHyperedgeLike[] = [
+        { comprehensive: 'focus', members: ['a', 'b'], muteKey: '__partitive__' },
+      ];
+      const visible = visibleNodeIds(nodes, links, new Set(), new Set(), hyperedges);
+      expect(visible.has('focus')).toBe(true);
+      expect(visible.has('a')).toBe(true);
+      expect(visible.has('b')).toBe(true);
+    });
+
+    it('hyperedge members disappear when the bundle is muted', () => {
+      const nodes = [focus, a, b];
+      const links: Array<{ source: string; target: string; type: string }> = [];
+      const hyperedges: SphereHyperedgeLike[] = [
+        { comprehensive: 'focus', members: ['a', 'b'], muteKey: '__partitive__' },
+      ];
+      const visible = visibleNodeIds(nodes, links, new Set(['__partitive__']), new Set(), hyperedges);
+      expect(visible.has('focus')).toBe(true);
+      expect(visible.has('a')).toBe(false);
+      expect(visible.has('b')).toBe(false);
+    });
+
+    it('all-visible when no mutes are set', () => {
+      const nodes = [focus, a, b, c, d];
+      const links = buildLinks([
+        ['focus', 'a', 'related'],
+        ['focus', 'b', 'see'],
+        ['focus', 'c', 'related'],
+        ['focus', 'd', 'references'],
+      ]);
+      const visible = visibleNodeIds(nodes, links, new Set(), new Set());
+      expect([...visible].sort()).toEqual(['a', 'b', 'c', 'd', 'focus']);
+    });
+  });
 });

package/src/components/RelationSphere.vue

@@ -21,11 +21,11 @@ import { easeInOutCubic, slerp, fibonacciSpherePosition, project, cardEdge, type
 import { UriRouter } from '../adapters/UriRouter';
 import { getPreferredTerm } from '../utils/concept-helpers';
 import { renderContent } from '../utils/content-renderer';
-import { hashSeed, expandParams, portSide, portPoint, idToUriGet } from '../utils/sphere-math';
+import { hashSeed, expandParams, portSide, portPoint, idToUriGet, visibleNodeIds } from '../utils/sphere-math';
 import { useI18n } from '../i18n';
 
 const { t, locale } = useI18n();
-import type { Concept, Manifest, GraphEdge, PartitiveRelationWire, PartitiveMemberWire } from '../adapters/types';
+import type { Concept, Manifest, GraphEdge, PartitiveRelationWire, PartitiveMemberWire, GenericRelationWire } from '../adapters/types';
 import { rakeStrokeStyle } from '../utils/partitive-multiplicity';
 import { drawRakeBundles } from './relation-sphere/rake-bundles';
 import { ensureMarkers, ensureTypeMarker } from './relation-sphere/svg-markers';
@@ -45,6 +45,7 @@ const props = defineProps<{
   registerId: string;
   edges: GraphEdge[];
   partitiveRelations?: PartitiveRelationWire[];
+  genericRelations?: GenericRelationWire[];
 }>();
 
 const emit = defineEmits<{
@@ -96,6 +97,13 @@ const mutedRegisters = ref<Set<string>>(new Set());
 const panelOpen = ref(true);
 const MAX_NODES = 36;
 
+/** Convert a concept URI to the internal `${registerId}/${conceptId}` node ID. */
+function uriToNodeId(uri: string): string {
+  const parsed = UriRouter.parseUri(uri);
+  if (parsed) return `${parsed.registerId}/${parsed.conceptId}`;
+  return uri;
+}
+
 /* Sphere-display language. Defaults to the i18n UI locale (which reads
    localStorage) so e.g. a user returning in French mode sees French
    terms by default. The user can override via the Language selector. */
@@ -403,16 +411,22 @@ function buildGraph() {
   nodes = Array.from(nodeMap.values());
   links = resultLinks;
 
-  /* Ensure every PartitiveRelation member is present in the graph
-     so the rake bundle can render. The comprehensive is normally the
-     focus; partitives may need to be added as depth-1 neighbors. */
-  for (const rel of props.partitiveRelations ?? []) {
+  /* Ensure every PartitiveRelation + GenericRelation member is present
+     in the graph so rake bundles can render. The comprehensive is
+     normally the focus; members may need to be added as depth-1
+     neighbors. */
+  const hyperedgeRelations: ReadonlyArray<PartitiveRelationWire | GenericRelationWire> = [
+    ...(props.partitiveRelations ?? []),
+    ...(props.genericRelations ?? []),
+  ];
+  for (const rel of hyperedgeRelations) {
     const compParsed = UriRouter.parseUri(rel.comprehensive);
     if (!compParsed) continue;
     const compNodeId = `${compParsed.registerId}/${compParsed.conceptId}`;
     if (!nodeMap.has(compNodeId)) continue;
 
-    for (const member of rel.partitives) {
+    const members = 'partitives' in rel ? rel.partitives : rel.members;
+    for (const member of members) {
       const parsed = UriRouter.parseUri(member.uri);
       if (!parsed) continue;
       const nid = `${parsed.registerId}/${parsed.conceptId}`;
@@ -691,6 +705,30 @@ function drawEdges(cx: number, cy: number) {
     isMuted: mutedTypes.value.has('__partitive__'),
     relations: props.partitiveRelations ?? [],
   });
+
+  /* Generic relations render as rake bundles in a distinct hue (amber).
+     Member shape differs (delimitingCharacteristic instead of isDelimiting),
+     so normalize to the partitive-shaped input the renderer expects. */
+  const genericNormalized: PartitiveRelationWire[] = (props.genericRelations ?? []).map(rel => ({
+    source: rel.source,
+    comprehensive: rel.comprehensive,
+    completeness: rel.completeness,
+    register: rel.register,
+    partitives: rel.members.map(m => ({
+      uri: m.uri,
+      presence: m.presence,
+      count: m.count,
+      /* Every generic member is delimiting by definition (each carries
+         its own delimiting characteristic per ISO 704 §5.5.4.2.1). */
+      isDelimiting: true,
+    })),
+  }));
+  drawRakeBundles(svg, pos, {
+    isDark: uiStore.isDark,
+    color: uiStore.isDark ? '#fbbf24' : '#b45309',
+    isMuted: mutedTypes.value.has('__generic__'),
+    relations: genericNormalized,
+  });
 }
 
 /* ── Render DOM nodes ───────────────────────────────────── */
@@ -702,9 +740,34 @@ function renderDOM() {
   const cx = c ? c.clientWidth / 2 : 0;
   const cy = c ? c.clientHeight * 0.46 : 0;
 
+  /* Cards with no visible edges (after applying type + register mutes)
+     float with no connections — hide them so toggling a relation type
+     cleans up orphaned cards. Focus node (depth 0) always renders.
+     Hyperedge members are always visible while their bundle is not
+     muted, even when they have no bilateral edges, so the rake has a
+     card to point at. */
+  const hyperedgesForVisibility = [
+    ...(props.partitiveRelations ?? []).map(rel => ({
+      comprehensive: uriToNodeId(rel.comprehensive),
+      members: rel.partitives.map(m => uriToNodeId(m.uri)),
+      muteKey: '__partitive__',
+    })),
+    ...(props.genericRelations ?? []).map(rel => ({
+      comprehensive: uriToNodeId(rel.comprehensive),
+      members: rel.members.map(m => uriToNodeId(m.uri)),
+      muteKey: '__generic__',
+    })),
+  ];
+  const visibleIds = visibleNodeIds(
+    nodes,
+    links,
+    mutedTypes.value,
+    mutedRegisters.value,
+    hyperedgesForVisibility,
+  );
+
   for (const n of nodes) {
-    /* Skip muted-register nodes (except focus) */
-    if (n.depth !== 0 && mutedRegisters.value.has(n.register)) continue;
+    if (!visibleIds.has(n.id)) continue;
 
     const dsColor = getColor(n.register) || '#888';
     const el = document.createElement('div');
@@ -1020,6 +1083,16 @@ const legendItems = computed(() => {
       count: partitiveCount,
     });
   }
+  /* Synthetic entry for GenericRelations — same idea, distinct hue. */
+  const genericCount = props.genericRelations?.length ?? 0;
+  if (genericCount > 0) {
+    typeMap.set('__generic__', {
+      type: '__generic__',
+      label: 'generic relation',
+      color: uiStore.isDark ? '#fbbf24' : '#b45309',
+      count: genericCount,
+    });
+  }
   return Array.from(typeMap.values()).sort((a, b) => b.count - a.count);
 });
 
@@ -1164,6 +1237,9 @@ function toggleType(type: string) {
   mutedTypes.value = n;
   const c = canvasRef.value;
   if (c) drawEdges(c.clientWidth / 2, c.clientHeight * 0.46);
+  /* Re-render cards so nodes whose only edges were the toggled type
+     disappear (and reappear when the type is unmuted). */
+  renderDOM();
   /* Re-heat the simulation so nodes drift to a new equilibrium with
      the freed/hidden edges. The link force reads mutedTypes each tick,
      so toggling effectively "removes" the edge from the force calc. */

package/src/utils/sphere-math.ts

@@ -52,3 +52,85 @@ export function idToUriGet(map: Map<string, string>, uri: string): string | unde
   for (const [id, u] of map) if (u === uri) return id;
   return undefined;
 }
+
+export interface SphereNodeLike {
+  id: string;
+  register: string;
+  depth: number;
+}
+
+export interface SphereLinkLike {
+  source: string;
+  target: string;
+  type: string;
+}
+
+export interface SphereHyperedgeLike {
+  /** Node ID of the comprehensive concept. */
+  comprehensive: string;
+  /** Node IDs of the member concepts. */
+  members: readonly string[];
+  /** Mute key — when present in mutedTypes, the whole hyperedge is hidden. */
+  muteKey?: string;
+}
+
+/**
+ * IDs of nodes that should render given the current mute state.
+ *
+ * The focus node (depth 0) is always visible. Every other node must have
+ * at least one edge whose type is not muted AND whose other endpoint is
+ * not in a muted register — OR be a member of a non-muted hyperedge —
+ * otherwise the card floats with no connections and should disappear
+ * when its relations are hidden.
+ *
+ * Hyperedge membership counts as a "visible edge" because rake bundles
+ * are the connection: a member with no bilateral edges still needs its
+ * card rendered so the rake has something to point at.
+ *
+ * Extracted as a pure function so the visibility contract can be tested
+ * without mounting the sphere component.
+ */
+export function visibleNodeIds(
+  nodes: readonly SphereNodeLike[],
+  links: readonly SphereLinkLike[],
+  mutedTypes: ReadonlySet<string>,
+  mutedRegisters: ReadonlySet<string>,
+  hyperedges: readonly SphereHyperedgeLike[] = [],
+): Set<string> {
+  const byId = new Map<string, SphereNodeLike>();
+  for (const n of nodes) byId.set(n.id, n);
+
+  /* Pre-compute node IDs that participate in a non-muted hyperedge. */
+  const hyperedgeNodeIds = new Set<string>();
+  for (const he of hyperedges) {
+    if (he.muteKey && mutedTypes.has(he.muteKey)) continue;
+    hyperedgeNodeIds.add(he.comprehensive);
+    for (const m of he.members) hyperedgeNodeIds.add(m);
+  }
+
+  const visible = new Set<string>();
+  for (const n of nodes) {
+    if (n.depth === 0) {
+      visible.add(n.id);
+      continue;
+    }
+    if (mutedRegisters.has(n.register)) continue;
+    if (hyperedgeNodeIds.has(n.id)) {
+      visible.add(n.id);
+      continue;
+    }
+    for (const l of links) {
+      if (mutedTypes.has(l.type)) continue;
+      const otherId = l.source === n.id ? l.target : l.target === n.id ? l.source : null;
+      if (!otherId) continue;
+      const other = byId.get(otherId);
+      if (!other) continue;
+      if (other.depth !== 0 && mutedRegisters.has(other.register)) continue;
+      visible.add(n.id);
+      break;
+    }
+  }
+  return visible;
+}
+
+

package/src/views/ConceptView.vue

@@ -59,7 +59,7 @@ const edges = computed(() => store.conceptEdges);
 const activeRegisterId = computed(() => sphereFocusPayload.value?.registerId ?? props.registerId);
 const adjacent = ref({ prev: null as string | null, next: null as string | null });
 
-const { conceptPartitiveRelations } = useConceptEdges(
+const { conceptPartitiveRelations, conceptGenericRelations } = useConceptEdges(
   concept,
   activeRegisterId,
   manifest,
@@ -289,6 +289,7 @@ onUnmounted(() => window.removeEventListener('keydown', onKeydown));
           :register-id="activeRegisterId"
           :edges="edges"
           :partitive-relations="conceptPartitiveRelations"
+          :generic-relations="conceptGenericRelations"
           @navigate="onSphereNavigate"
         />
         <!-- Detail mode -->