@glossarist/concept-browser 0.7.51 → 0.7.52

package/src/composables/useDatasetSeries.ts

@@ -0,0 +1,258 @@
+/**
+ * Dataset series — groups related editions of the same vocabulary.
+ *
+ * A "series" is a family of datasets that share a base name but differ in
+ * edition year/status. e.g. `viml-2022`, `viml-2013`, `viml-2000`, `viml-1968`
+ * all belong to the `viml` series.
+ *
+ * Resolution order (most authoritative first):
+ *   1. Explicit `datasetGroups` from site-config with `series: true` —
+ *      config-driven series have stable ids, labels, and orderings.
+ *   2. Auto-derivation by naming convention — `name-YYYY` → `name`. Used
+ *      only when NO configured groups exist (backward compat).
+ *
+ * Within a series, editions are sorted by year ascending so the timeline
+ * reads naturally left-to-right / top-to-bottom.
+ */
+
+import { computed } from 'vue';
+import { useVocabularyStore } from '../stores/vocabulary';
+import { useSiteConfig } from '../config/use-site-config';
+import { resolveGroupKind } from '../config/group-types';
+import type { Manifest } from '../adapters/types';
+
+export interface DatasetSeriesMember {
+  id: string;
+  ref: string;
+  year?: number;
+  status: string;
+  isCurrent: boolean;
+  isActive: boolean;
+  conceptCount?: number;
+  registerId: string;
+}
+
+export interface DatasetSeries {
+  /** Stable series key, e.g. `viml`. */
+  key: string;
+  /** Display title for the series, e.g. `VIML` or `International Vocabulary of Legal Metrology`. */
+  title: string;
+  /** Optional description from config. */
+  description?: string;
+  /** Optional accent color from config. Accepts single hex or { light, dark }. */
+  color?: string | { light: string; dark: string };
+  /** All known editions, oldest first. */
+  members: DatasetSeriesMember[];
+  /** The current (newest valid) member, if any. */
+  current?: DatasetSeriesMember;
+  /** Total concept count across the series (sum of members). */
+  totalConcepts: number;
+  /** Whether this series was explicitly configured (vs auto-derived). */
+  configured: boolean;
+}
+
+const YEAR_SUFFIX = /[-_:](\d{4})([a-z]?)$/i;
+
+/** Strip trailing year from a dataset id to get the series key. */
+export function deriveSeriesKey(id: string): string {
+  return id.replace(YEAR_SUFFIX, '').replace(/[-_:]+$/, '');
+}
+
+/** Extract a year from a string. Prefers the ISO convention
+ *  (`:YYYY`, `:YYYYa`) used in ISO/IEC standard references, then
+ *  falls back to a year-as-suffix match (`-YYYY`, `_YYYY`, ` YYYY`),
+ *  then a bare 4-digit year. Returns undefined for out-of-range or
+ *  4-digit runs that are clearly standard numbers (e.g. `ISO 10241`
+ *  → 1024 is rejected because it's not preceded by `:`). */
+export function extractYear(source: string): number | undefined {
+  if (!source) return undefined;
+  const isoMatch = source.match(/:(\d{4})([a-z]?)$/i);
+  if (isoMatch) {
+    const year = parseInt(isoMatch[1], 10);
+    if (year >= 1900 && year <= 2100) return year;
+  }
+  const suffixMatch = source.match(/[-_\s](\d{4})([a-z]?)$/i);
+  if (suffixMatch) {
+    const year = parseInt(suffixMatch[1], 10);
+    if (year >= 1900 && year <= 2100) return year;
+  }
+  if (/^\d{4}$/.test(source.trim())) {
+    const year = parseInt(source.trim(), 10);
+    if (year >= 1900 && year <= 2100) return year;
+  }
+  return undefined;
+}
+
+/** Build the series title from a member — `OIML V 1:2022` → `OIML V 1`.
+ *  Returns the dataset id when the manifest is unavailable. */
+function deriveSeriesTitle(m: Manifest | undefined): string {
+  if (!m) return '';
+  const ref = m.ref ?? m.title;
+  return ref.replace(/[:\s-]\d{4}([a-z]?)$/i, '').trim() || m.title;
+}
+
+function manifestToMember(m: Manifest, activeDatasetId?: string): DatasetSeriesMember {
+  const year = extractYear(m.id) ?? extractYear(m.ref ?? '') ?? extractYear(m.title);
+  return {
+    id: m.id,
+    ref: m.ref ?? m.title,
+    year,
+    status: m.status ?? m.editionStatus ?? 'unknown',
+    isCurrent: false,
+    isActive: m.id === activeDatasetId,
+    conceptCount: m.conceptCount,
+    registerId: m.id,
+  };
+}
+
+/**
+ * Group manifests into series. Pure function.
+ *
+ * Strategy:
+ *   1. If `configuredGroups` is provided AND has any group whose `kind` is
+ *      `lineage` (or the legacy `series: true` flag), use ONLY configured
+ *      lineage groups — config is the source of truth.
+ *   2. Otherwise, fall back to auto-derivation by naming convention.
+ */
+export function groupManifestsIntoSeries(
+  manifests: Manifest[],
+  activeDatasetId?: string,
+  configuredGroups?: Array<{
+    id: string;
+    label?: string;
+    description?: string;
+    color?: string | { light: string; dark: string };
+    datasets: string[];
+    series?: boolean;
+    kind?: 'lineage' | 'topic' | 'family' | 'collection' | 'default';
+    current?: string;
+  }>,
+): DatasetSeries[] {
+  const manifestMap = new Map(manifests.map(m => [m.id, m] as const));
+
+  /* Strategy 1: config-driven lineage series */
+  const configSeries = (configuredGroups ?? []).filter(g => resolveGroupKind(g) === 'lineage');
+  if (configSeries.length > 0) {
+    const series: DatasetSeries[] = [];
+    for (const g of configSeries) {
+      const members: DatasetSeriesMember[] = [];
+      /* Include EVERY dataset in the config, even if its manifest isn't loaded
+         yet. Without this, visiting /dataset/viml-2000 (only manifest loaded)
+         would shrink the series to one member and mis-mark viml-2000 as current. */
+      for (const id of g.datasets) {
+        const m = manifestMap.get(id);
+        if (m) {
+          members.push(manifestToMember(m, activeDatasetId));
+        } else {
+          /* Stub member from id alone — year derived from `<name>-YYYY` pattern. */
+          members.push({
+            id,
+            ref: id,
+            year: extractYear(id),
+            status: 'unknown',
+            isCurrent: false,
+            isActive: id === activeDatasetId,
+            conceptCount: undefined,
+            registerId: id,
+          });
+        }
+      }
+      if (members.length === 0) continue;
+      members.sort((a, b) => (a.year ?? 0) - (b.year ?? 0));
+
+      /* Determine current edition:
+         1. Explicit `current` field from config (most authoritative)
+         2. Newest member with status='valid'
+         3. Last member (newest by year) */
+      let current: DatasetSeriesMember | undefined;
+      if (g.current) {
+        current = members.find(m => m.id === g.current);
+      }
+      if (!current) {
+        const validMembers = members.filter(m => m.status === 'valid');
+        current = validMembers[validMembers.length - 1] ?? members[members.length - 1];
+      }
+      if (current) current.isCurrent = true;
+
+      const totalConcepts = members.reduce((sum, m) => sum + (m.conceptCount ?? 0), 0);
+      series.push({
+        key: g.id,
+        title: g.label ?? (deriveSeriesTitle(manifestMap.get(members[0].id)) || g.id),
+        description: g.description,
+        color: g.color,
+        members,
+        current,
+        totalConcepts,
+        configured: true,
+      });
+    }
+    return series;
+  }
+
+  /* Strategy 2: auto-derive by naming convention */
+  const groups = new Map<string, Manifest[]>();
+  for (const m of manifests) {
+    const key = deriveSeriesKey(m.id);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key)!.push(m);
+  }
+
+  const series: DatasetSeries[] = [];
+  for (const [key, members] of groups) {
+    if (members.length === 0) continue;
+    const enriched = members.map(m => manifestToMember(m, activeDatasetId));
+    enriched.sort((a, b) => (a.year ?? 0) - (b.year ?? 0));
+    const validMembers = enriched.filter(m => m.status === 'valid');
+    const current = validMembers[validMembers.length - 1] ?? enriched[enriched.length - 1];
+    if (current) current.isCurrent = true;
+    const totalConcepts = enriched.reduce((sum, m) => sum + (m.conceptCount ?? 0), 0);
+    series.push({
+      key,
+      title: deriveSeriesTitle(members[0]),
+      members: enriched,
+      current,
+      totalConcepts,
+      configured: false,
+    });
+  }
+
+  series.sort((a, b) => a.key.localeCompare(b.key));
+  return series;
+}
+
+/**
+ * Composable — exposes series for the currently-loaded datasets.
+ * Reactive: re-derives when the store's dataset list changes.
+ */
+export function useDatasetSeries(activeDatasetId?: () => string | undefined) {
+  const store = useVocabularyStore();
+  const { datasetGroups } = useSiteConfig();
+
+  const series = computed<DatasetSeries[]>(() => {
+    const manifests: Manifest[] = [];
+    for (const [, adapter] of store.datasets.entries()) {
+      const m = adapter.manifest;
+      if (m) manifests.push(m);
+    }
+    const activeId = activeDatasetId?.();
+    const configured = datasetGroups.value?.map(g => ({
+      id: g.id,
+      label: g.label,
+      description: g.description,
+      color: g.color,
+      datasets: g.datasets,
+      series: g.series,
+      kind: g.kind,
+      current: g.current,
+    }));
+    return groupManifestsIntoSeries(manifests, activeId, configured);
+  });
+
+  const seriesForActive = computed<DatasetSeries | undefined>(() => {
+    const activeId = activeDatasetId?.();
+    if (!activeId) return undefined;
+    return series.value.find(s => s.members.some(m => m.id === activeId));
+  });
+
+  return { series, seriesForActive };
+}

package/src/composables/useSphereProjection.ts

@@ -0,0 +1,125 @@
+/**
+ * Sphere projection + force-layout math for RelationSphere.
+ *
+ * All functions are pure — no Vue, no DOM. The component passes positions in,
+ * gets screen coordinates out. This keeps the math testable and the component
+ * focused on rendering.
+ *
+ * Coordinates: unit sphere (‖p‖ = 1). The "front pole" is (0, 0, 1) — the
+ * focal point of the camera. The simulation runs in 3D and is projected to
+ * 2D with perspective at render time.
+ */
+
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/** Perspective projection constants — tuned for unit sphere. */
+const FOCAL = 600;
+const Z_OFFSET = 800;
+const SPHERE_R = 360;
+
+/** Slow-fast-slow easing — cubic ease-in-out. */
+export function easeInOutCubic(t: number): number {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
+
+/** Great-circle interpolation between two unit-sphere points. */
+export function slerp(a: Vec3, b: Vec3, t: number): Vec3 {
+  const dot = Math.max(-1, Math.min(1, a.x * b.x + a.y * b.y + a.z * b.z));
+  const omega = Math.acos(dot);
+  if (omega < 0.001) {
+    return {
+      x: a.x + (b.x - a.x) * t,
+      y: a.y + (b.y - a.y) * t,
+      z: a.z + (b.z - a.z) * t,
+    };
+  }
+  const sinO = Math.sin(omega);
+  const wa = Math.sin((1 - t) * omega) / sinO;
+  const wb = Math.sin(t * omega) / sinO;
+  return {
+    x: a.x * wa + b.x * wb,
+    y: a.y * wa + b.y * wb,
+    z: a.z * wa + b.z * wb,
+  };
+}
+
+/**
+ * Initial sphere position by depth band. Focus at (0,0,1); 1°/2°/3° neighbors
+ * distributed at increasing angular distance from the focus.
+ *
+ * Depth 1 forms an EVEN ring (best spacing for small N). Deeper levels use
+ * the golden-angle offset so they interleave with the previous ring.
+ */
+export function fibonacciSpherePosition(
+  depth: number,
+  idx: number,
+  total: number,
+  jitterSeed: number,
+): Vec3 {
+  if (depth === 0) return { x: 0, y: 0, z: 1 };
+  /* Angular distance from north pole — each ring further out. */
+  const thetaByDepth: Record<number, number> = { 1: 1.15, 2: 1.55, 3: 1.95 };
+  const theta = thetaByDepth[depth] ?? 1.15;
+  const j = (jitterSeed % 7) * 0.008;
+  const t = theta + j;
+  let phi: number;
+  if (depth === 1) {
+    /* Even ring for depth 1 — gives best spread for small N */
+    phi = (idx / Math.max(total, 1)) * Math.PI * 2;
+  } else {
+    /* Golden-angle spiral for deeper rings, offset by depth so rings interleave */
+    phi = (idx * 2.39996 + depth * 1.7 + (jitterSeed % 11) * 0.4) % (Math.PI * 2);
+  }
+  return {
+    x: Math.sin(t) * Math.cos(phi),
+    y: Math.sin(t) * Math.sin(phi),
+    z: Math.cos(t),
+  };
+}
+
+/** 3D unit-sphere point → 2D screen offset from sphere center. */
+export interface Projected {
+  x: number;
+  y: number;
+  scale: number;
+  z: number;
+}
+
+export function project(p: Vec3): Projected {
+  const persp = FOCAL / (Z_OFFSET - p.z * SPHERE_R);
+  return {
+    x: p.x * SPHERE_R * persp,
+    y: -p.y * SPHERE_R * persp,
+    scale: persp,
+    z: p.z,
+  };
+}
+
+/**
+ * Find the point on a rectangle's edge in the direction of an external point.
+ * Used so SVG edge paths start/end on the rim of the card, not its center.
+ */
+export function cardEdge(
+  from: { x: number; y: number },
+  to: { x: number; y: number },
+  w: number,
+  h: number,
+): { x: number; y: number } {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const len = Math.sqrt(dx * dx + dy * dy) || 1;
+  const ux = dx / len;
+  const uy = dy / len;
+  const absUx = Math.abs(ux);
+  const absUy = Math.abs(uy);
+  const halfW = w / 2;
+  const halfH = h / 2;
+  const tX = absUx > 0.001 ? halfW / absUx : Infinity;
+  const tY = absUy > 0.001 ? halfH / absUy : Infinity;
+  const t = Math.min(tX, tY);
+  return { x: from.x + ux * t, y: from.y + uy * t };
+}

package/src/config/group-types.ts

@@ -0,0 +1,92 @@
+/**
+ * Dataset group type registry.
+ *
+ * Maps each `DatasetGroupKind` to its semantic metadata. Adding a new kind
+ * is a single entry here + a new renderer component — no edits to existing
+ * components needed (open/closed principle).
+ *
+ * The registry is intentionally pure data — no Vue imports — so it can be
+ * consumed by both the sidebar (compact rendering) and the home page (rich
+ * rendering) without coupling.
+ */
+import type { DatasetGroupKind } from './types';
+
+export interface GroupTypeMeta {
+  /** Discriminator value matching `DatasetGroup.kind`. */
+  kind: DatasetGroupKind;
+  /** Human label for the kind, e.g. "Edition series". */
+  label: string;
+  /** Short description shown in tooltips / section headers. */
+  description: string;
+  /** Icon glyph — used in section headers and breadcrumbs. */
+  glyph: string;
+  /** Whether members have an inherent temporal ordering. */
+  ordered: boolean;
+  /** Whether members have a supersession chain (newer supersedes older). */
+  supersession: boolean;
+  /** Whether members share the same vocabulary identity across editions. */
+  sameVocabulary: boolean;
+}
+
+export const GROUP_TYPES: Record<DatasetGroupKind, GroupTypeMeta> = {
+  lineage: {
+    kind: 'lineage',
+    label: 'Edition series',
+    description: 'Same vocabulary, different editions over time',
+    glyph: '⏳',
+    ordered: true,
+    supersession: true,
+    sameVocabulary: true,
+  },
+  topic: {
+    kind: 'topic',
+    label: 'Topic bundle',
+    description: 'Different vocabularies covering the same subject',
+    glyph: '◆',
+    ordered: false,
+    supersession: false,
+    sameVocabulary: false,
+  },
+  family: {
+    kind: 'family',
+    label: 'Publication family',
+    description: 'Related vocabularies from the same publisher or program',
+    glyph: '✦',
+    ordered: false,
+    supersession: false,
+    sameVocabulary: false,
+  },
+  collection: {
+    kind: 'collection',
+    label: 'Curated collection',
+    description: 'Hand-picked bundle of datasets for a specific audience',
+    glyph: '❖',
+    ordered: false,
+    supersession: false,
+    sameVocabulary: false,
+  },
+  default: {
+    kind: 'default',
+    label: 'Datasets',
+    description: 'Grouped datasets',
+    glyph: '▸',
+    ordered: false,
+    supersession: false,
+    sameVocabulary: false,
+  },
+};
+
+/**
+ * Normalize a group config (which may use the legacy `series: true` flag or
+ * the new `kind` discriminator) into a canonical `kind`. Pure function.
+ */
+export function resolveGroupKind(group: { kind?: DatasetGroupKind; series?: boolean }): DatasetGroupKind {
+  if (group.kind) return group.kind;
+  if (group.series) return 'lineage';
+  return 'default';
+}
+
+/** Lookup the metadata for any group, using `resolveGroupKind` for compat. */
+export function groupTypeMeta(group: { kind?: DatasetGroupKind; series?: boolean }): GroupTypeMeta {
+  return GROUP_TYPES[resolveGroupKind(group)];
+}

package/src/config/types.ts

@@ -82,6 +82,8 @@ export interface RoutingEntry {
 
 // === Dataset ===
 
+export type DatasetColorSpec = string | { light: string; dark: string };
+
 export interface DatasetConfig {
   id: string;
   uri: string;
@@ -92,7 +94,13 @@ export interface DatasetConfig {
   title: string;
   description?: string;
   owner?: string;
-  color?: string;
+  /**
+   * Dataset accent color. Accepts either a single hex (applied to both
+   * light and dark modes) or an explicit `{ light, dark }` pair.
+   * Per-deployment overrides via `site-config.json` `colors.dataset[id]`
+   * take precedence.
+   */
+  color?: DatasetColorSpec;
   tags?: string[];
   languageOrder?: string[];
   ref?: string;
@@ -142,17 +150,86 @@ export interface PageConfig {
 
 // === Dataset Groups ===
 
+/**
+ * Kind of dataset group. Determines how the group is rendered in the sidebar
+ * and home page, and what semantic relationships between members are assumed.
+ *
+ * - `lineage` — same vocabulary, different editions (e.g. VIML 1968/2000/2013/2022).
+ *   Members have temporal ordering and a supersession chain. Rendered as a
+ *   timeline with year badges and "current" markers.
+ *
+ * - `topic` — different vocabularies on the same subject (e.g. three SDOs
+ *   publishing "intelligent transport systems" terminology). Members may
+ *   overlap in concepts but have no temporal ordering. Rendered as a card
+ *   grid with overlap indicators.
+ *
+ * - `family` — related vocabularies from the same publisher or program
+ *   (e.g. all OIML publications). Hierarchical grouping, no required
+ *   relationships between members. Rendered as a flat list under a labeled
+ *   header.
+ *
+ * - `collection` — curated bundle of datasets (e.g. "Starter pack for new
+ *   metrologists"). Arbitrary selection, often cross-publisher. Rendered as
+ *   a featured card with custom descriptions.
+ *
+ * - `default` (omitted) — backward-compatible flat list. No special
+ *   semantics. Used when no `kind` is specified.
+ *
+ * The registry in `src/config/group-types.ts` maps each kind to its renderer
+ * component, so new kinds can be added without modifying existing code
+ * (open/closed principle).
+ */
+export type DatasetGroupKind = 'lineage' | 'topic' | 'family' | 'collection' | 'default';
+
 export interface DatasetGroup {
   id: string;
   label: string;
   description?: string;
-  color?: string;
+  /**
+   * Group accent color. Same shape as DatasetConfig.color.
+   * Per-deployment overrides via `site-config.json` `colors.group[id]`.
+   */
+  color?: DatasetColorSpec;
   datasets: string[];
   translations?: Record<string, { label?: string; description?: string }>;
+  /**
+   * Discriminator for the group's semantic type and UX. See DatasetGroupKind
+   * for the full list of supported values. Defaults to 'default' (flat list).
+   *
+   * Replaces the older `series?: boolean` flag — use `kind: lineage` instead.
+   */
+  kind?: DatasetGroupKind;
+  /**
+   * For lineage series: the dataset id of the current (newest valid) edition.
+   * If omitted, the newest member by year (or last in `datasets` order) is
+   * used. Setting this explicitly avoids misdetection when only a subset of
+   * editions happen to be loaded.
+   */
+  current?: string;
+  /**
+   * @deprecated Use `kind: 'lineage'` instead. Still respected as a
+   * backward-compat shorthand: `series: true` is treated as `kind: 'lineage'`.
+   */
+  series?: boolean;
 }
 
 // === Site Config ===
 
+export interface SiteColors {
+  /** Per-dataset color overrides. Keyed by dataset id. */
+  dataset?: Record<string, DatasetColorSpec>;
+  /** Per-group color overrides. Keyed by group id. */
+  group?: Record<string, DatasetColorSpec>;
+  /** Per-relation-type color overrides. Keyed by type id (e.g. "supersedes"). */
+  relationshipType?: Record<string, DatasetColorSpec>;
+  /** Per-relation-category color overrides. Keyed by category id (e.g. "lifecycle"). */
+  relationshipCategory?: Record<string, DatasetColorSpec>;
+  /** Per-concept-status color overrides. Keyed by status id. */
+  conceptStatus?: Record<string, DatasetColorSpec>;
+  /** Per-group-kind color overrides. Keyed by DatasetGroupKind. */
+  groupKind?: Record<string, DatasetColorSpec>;
+}
+
 export interface SiteConfig {
   id: string;
   domain: string;
@@ -171,6 +248,8 @@ export interface SiteConfig {
   social?: SocialLinks;
   nav?: NavItem[];
   footerNav?: NavItem[];
+  /** Color overrides. Merged over `data/colors.json` defaults. */
+  colors?: SiteColors;
   defaults: {
     language?: string;
     languageOrder?: string[];

package/src/config/use-site-config.ts

@@ -1,5 +1,5 @@
 import { ref, computed } from 'vue';
-import type { PageConfig } from './types';
+import type { PageConfig, SiteColors } from './types';
 import type { DatasetGroup } from './types';
 import { locale } from '../i18n';
 
@@ -38,6 +38,7 @@ export interface RuntimeSiteConfig {
   pages?: PageConfig[];
   contributors?: { name: string; role?: string; organization?: string; url?: string; email?: string }[];
   copyright?: string;
+  colors?: SiteColors;
 }
 
 const siteConfig = ref<RuntimeSiteConfig | null>(null);