@glossarist/concept-browser 0.7.43 → 0.7.45

package/src/utils/content-renderer.ts

@@ -5,28 +5,39 @@
  * math placeholders, tables, lists, and text formatting. This is the single
  * source of truth for content rendering in the browser.
  *
+ * Mention kinds routed here (all dispatched by glossarist's `parseMention`):
+ *   - {{fig:id}} / {{fig:id, display}}  → nonVerbalRefResolver (figure)
+ *   - {{table:id}} / {{table:id, display}}  → nonVerbalRefResolver (table)
+ *   - {{formula:id}} / {{formula:id, display}}  → nonVerbalRefResolver (formula)
+ *   - {{cite:key[, render term]}}  → citeResolver
+ *   - {{urn:...[, render term]}}  → urnRefResolver / xrefResolver
+ *   - {{concept_id[, render term]}}  → conceptRefResolver
+ *   - {{designation[, render term]}}  → conceptRefResolver
+ *
  * Math-specific helpers (replaceBracketed, mathPlaceholder) are internal.
- * The v-math directive upgrades the placeholders to KaTeX at runtime.
+ * The v-math directive upgrades the placeholders to Plurimath at runtime.
  */
 import { escapeHtml, escapeAttr } from './escape';
 import { parseMention } from 'glossarist';
+import type { NonVerbalKind } from '../adapters/non-verbal/types';
+import { entityKindFromMentionKind } from '../adapters/non-verbal/kind';
 
 // ── Resolver types ────────────────────────────────────────────────────────
 
 export type XrefResolver = (uri: string, term: string) => string;
 export type BibResolver = (refId: string, title: string) => string;
-export type FigResolver = (figId: string) => string;
 export type CiteResolver = (key: string, label: string | null) => string;
 export type ConceptRefResolver = (conceptId: string, term: string) => string;
 export type UrnRefResolver = (uri: string, term: string) => string;
+export type NonVerbalRefResolver = (kind: NonVerbalKind, entityId: string, display?: string) => string;
 
 export interface RenderOptions {
   xrefResolver?: XrefResolver;
   bibResolver?: BibResolver;
-  figResolver?: FigResolver;
   conceptRefResolver?: ConceptRefResolver;
   citeResolver?: CiteResolver;
   urnRefResolver?: UrnRefResolver;
+  nonVerbalRefResolver?: NonVerbalRefResolver;
 }
 
 // ── Math placeholders ────────────────────────────────────────────────────
@@ -144,19 +155,11 @@ function resolveBibRefs(text: string, opts: RenderOptions): string {
   });
 }
 
-function resolveFigRefs(text: string, opts: RenderOptions): string {
-  return text.replace(/<<(fig_[^>]+)>>/g, (_, figId) => {
-    if (opts.figResolver) {
-      return opts.figResolver(figId.trim());
-    }
-    return `<span class="fig-ref">${escapeHtml(figId.trim())}</span>`;
-  });
-}
-
 function resolveUrnRefs(text: string, opts: RenderOptions): string {
   // Double-brace URN refs: {{urn:...,term}} or {{urn:...,term,display}}
-  // Note: glossarist ≥ 0.3.7 parseMention handles these as 'urn-ref', but we
-  // keep this handler for when parseMention returns 'unresolved' (glossarist < 0.3.7)
+  // These bypass parseMention because the three-arg form has different
+  // semantics in the renderer (display shown, not term) vs. cleanContent
+  // (term shown for search indexing).
   let result = text.replace(/\{\{(urn:[^,}]+),([^,}]+)(?:,([^}]+))?\}\}/g, (_, uri, term, display) => {
     const t = (display || term).trim();
     if (opts.xrefResolver) {
@@ -178,60 +181,68 @@ function resolveUrnRefs(text: string, opts: RenderOptions): string {
 }
 
 function resolveMentions(text: string, opts: RenderOptions): string {
-  // Single-pass {{...}} mention dispatcher via parseMention (SSOT)
   return text.replace(/\{\{([^{}]+?)\}\}/g, (_orig, body) => {
     const parsed = parseMention(body);
+    const p = parsed as Record<string, unknown>;
+
+    switch (p.kind) {
+      case 'fig-ref':
+      case 'table-ref':
+      case 'formula-ref': {
+        const nvKind = entityKindFromMentionKind(p.kind as string) as NonVerbalKind;
+        const entityId = p.key as string;
+        const display = (p.label as string) ?? undefined;
+        if (opts.nonVerbalRefResolver) {
+          return opts.nonVerbalRefResolver(nvKind, entityId, display);
+        }
+        const label = display ?? entityId;
+        return `<span class="nv-ref nv-ref--${nvKind}">${escapeHtml(label)}</span>`;
+      }
 
-    // cite:key[,render term] — bibliography citation
-    if (parsed.kind === 'cite-ref') {
-      const key = parsed.key!;
-      const label = parsed.label ?? null;
-      if (opts.citeResolver) return opts.citeResolver(key, label);
-      return `<span class="bib-ref">${escapeHtml(label ?? key)}</span>`;
-    }
+      case 'cite-ref': {
+        const key = p.key as string;
+        const label = (p.label as string) ?? null;
+        if (opts.citeResolver) return opts.citeResolver(key, label);
+        return `<span class="bib-ref">${escapeHtml(label ?? key)}</span>`;
+      }
 
-    // urn:...[,render term] — URN cross-reference (glossarist ≥ 0.3.7)
-    const anyParsed = parsed as Record<string, unknown>;
-    if ((anyParsed.kind as string) === 'urn-ref') {
-      const uri = anyParsed.uri as string;
-      const label = (anyParsed.label as string) ?? uri;
-      if (opts.urnRefResolver) return opts.urnRefResolver(uri, label);
-      if (opts.xrefResolver) return opts.xrefResolver(uri, label);
-      return escapeHtml(label);
-    }
+      case 'urn-ref': {
+        const uri = p.uri as string;
+        const label = (p.label as string) ?? uri;
+        if (opts.urnRefResolver) return opts.urnRefResolver(uri, label);
+        if (opts.xrefResolver) return opts.xrefResolver(uri, label);
+        return escapeHtml(label);
+      }
 
-    // numeric_id[,render term] — local concept ID
-    if (parsed.kind === 'numeric') {
-      const id = parsed.id!;
-      const label = parsed.label;
-      if (label && opts.conceptRefResolver) {
-        return opts.conceptRefResolver(id, label);
+      case 'numeric': {
+        const id = p.id as string;
+        const label = p.label as string | null;
+        if (label && opts.conceptRefResolver) {
+          return opts.conceptRefResolver(id, label);
+        }
+        return `<span class="gl-mention">${escapeHtml(id)}</span>`;
       }
-      return `<span class="gl-mention">${escapeHtml(id)}</span>`;
-    }
 
-    // designation[,render term] — designation matching (glossarist ≥ 0.3.7)
-    if ((anyParsed.kind as string) === 'designation') {
-      const designation = anyParsed.id as string;
-      const label = (anyParsed.label as string) ?? designation;
-      if (opts.conceptRefResolver) {
-        return opts.conceptRefResolver(designation, label);
+      case 'designation': {
+        const designation = p.id as string;
+        const label = (p.label as string) ?? designation;
+        if (opts.conceptRefResolver) {
+          return opts.conceptRefResolver(designation, label);
+        }
+        return escapeHtml(label);
       }
-      return escapeHtml(label);
-    }
 
-    // Fallback for unresolved: handle two-arg form or render as plain text
-    // This handles cases where parseMention doesn't recognize the kind
-    // (e.g. glossarist < 0.3.7 before urn-ref/designation kinds were added)
-    const commaIdx = body.indexOf(',');
-    if (commaIdx > 0) {
-      const id = body.slice(0, commaIdx).trim();
-      const display = body.slice(commaIdx + 1).trim();
-      if (opts.conceptRefResolver) return opts.conceptRefResolver(id, display);
-      return escapeHtml(display);
+      default: {
+        const commaIdx = body.indexOf(',');
+        if (commaIdx > 0) {
+          const id = body.slice(0, commaIdx).trim();
+          const display = body.slice(commaIdx + 1).trim();
+          if (opts.conceptRefResolver) return opts.conceptRefResolver(id, display);
+          return escapeHtml(display);
+        }
+        return `<span class="gl-mention">${escapeHtml(body.trim())}</span>`;
+      }
     }
-
-    return `<span class="gl-mention">${escapeHtml(body.trim())}</span>`;
   });
 }
 
@@ -246,9 +257,9 @@ function resolveMentions(text: string, opts: RenderOptions): string {
  * 3. Bullet and numbered lists
  * 4. Text formatting (bold, italic, subscript)
  * 5. Bibliography cross-references (<<ref,title>>)
- * 6. Figure references (<<fig_...>>)
- * 7. Single-brace URN inline references ({urn:...})
- * 8. Mention dispatcher via parseMention (cite-ref, urn-ref, numeric, designation)
+ * 6. Single-brace URN inline references ({urn:...})
+ * 7. Mention dispatcher — non-verbal (fig/table/formula), then parseMention
+ *    (cite-ref, urn-ref, numeric, designation)
  */
 export function renderContent(text: string, xrefResolverOrOpts?: XrefResolver | RenderOptions): string {
   if (!text) return '';
@@ -273,10 +284,9 @@ export function renderContent(text: string, xrefResolverOrOpts?: XrefResolver |
 
   // Stage 4: Reference resolution
   result = resolveBibRefs(result, opts);
-  result = resolveFigRefs(result, opts);
   result = resolveUrnRefs(result, opts);
 
-  // Stage 5: Mention dispatcher (parseMention SSOT)
+  // Stage 5: Mention dispatcher (non-verbal first, then parseMention SSOT)
   result = resolveMentions(result, opts);
 
   return result;
@@ -295,7 +305,9 @@ export function cleanContent(text: string): string {
     .replace(/~([^~]+)~/g, '_$1')
     .replace(/\n[ \t]*\* /g, '; ')
     .replace(/<<([^,>]+),([^>]+)>>/g, '$2')
-    .replace(/<<(fig_[^>]+)>>/g, '$1')
+    // Non-verbal mentions: {{fig:id, display}} → display; {{fig:id}} → id
+    .replace(/\{\{(?:fig|figure|table|tbl|formula|eq):([^,}]+),\s*([^}]+)\}\}/g, '$2')
+    .replace(/\{\{(?:fig|figure|table|tbl|formula|eq):([^}]+)\}\}/g, '$1')
     // URN refs — show render term (second part for two-arg, third part for three-arg)
     .replace(/\{\{urn:[^,}]+,([^,}]+),([^}]+)\}\}/g, '$1')  // three-arg: {{urn:...,term,display}} → term
     .replace(/\{\{urn:[^,}]+(?:,([^}]+))?\}\}/g, (_, label) => label ? label.trim() : '')  // two-arg or bare

package/src/utils/locale.ts

@@ -0,0 +1,92 @@
+/**
+ * Locale fallback SSOT.
+ *
+ * Single source of truth for localized text resolution across the runtime.
+ * Both the non-verbal entity resolver and any other localized content
+ * resolution should call `pickLocaleText` / `pickLocaleMap` rather than
+ * implement their own fallback chain.
+ */
+
+import { fetchLocalizedString } from 'glossarist';
+
+const DEFAULT_FALLBACK_CHAIN: readonly string[] = ['eng'] as const;
+
+const RTL_LOCALES: ReadonlySet<string> = new Set(['ara', 'heb', 'fas', 'urd', 'arb']);
+
+const ISO_639_2_TO_BCP47: 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',
+};
+
+export type LocalizedText = Record<string, string>;
+
+export interface ResolvedLocaleText {
+  locale: string;
+  text: string;
+}
+
+export function pickLocaleText(
+  map: LocalizedText | undefined,
+  locale: string,
+  fallbackChain: readonly string[] = DEFAULT_FALLBACK_CHAIN,
+): string {
+  const r = pickLocaleMap(map, locale, fallbackChain);
+  return r?.text ?? '';
+}
+
+export function pickLocaleMap(
+  map: LocalizedText | undefined,
+  locale: string,
+  fallbackChain: readonly string[] = DEFAULT_FALLBACK_CHAIN,
+): ResolvedLocaleText | null {
+  if (!map) return null;
+
+  // Disable fetchLocalizedString's built-in 'eng' default by passing null —
+  // at runtime `null` defeats the default param and the `!= null` guard
+  // inside the lib skips its own fallback. The published .d.ts types the
+  // parameter as `string | undefined`, so cast through `unknown`. The chain
+  // is owned by THIS module: callers see one predictable resolution order.
+  const noFallback = null as unknown as undefined;
+  const direct = fetchLocalizedString(map, locale, noFallback);
+  if (direct != null) return { locale, text: direct };
+
+  for (const l of fallbackChain) {
+    const fb = fetchLocalizedString(map, l, noFallback);
+    if (fb != null) return { locale: l, text: fb };
+  }
+
+  const entries = Object.entries(map);
+  if (entries.length === 0) return null;
+  return { locale: entries[0][0], text: entries[0][1] };
+}
+
+export function hasLocale(map: LocalizedText | undefined, locale: string): boolean {
+  return !!map && Object.prototype.hasOwnProperty.call(map, locale);
+}
+
+export function isRtl(locale: string): boolean {
+  return RTL_LOCALES.has(locale);
+}
+
+export function localeToBcp47(locale: string): string {
+  return ISO_639_2_TO_BCP47[locale] ?? locale;
+}
+
+export function resolveFallbackChain(datasetLocales?: readonly string[]): readonly string[] {
+  if (!datasetLocales || datasetLocales.length === 0) {
+    return DEFAULT_FALLBACK_CHAIN;
+  }
+  const chain = [...datasetLocales];
+  for (const l of DEFAULT_FALLBACK_CHAIN) {
+    if (!chain.includes(l)) chain.push(l);
+  }
+  return chain;
+}

package/src/utils/non-verbal-anchor.ts

@@ -0,0 +1,51 @@
+/**
+ * Anchor scheme SSOT for non-verbal entities.
+ *
+ * The anchor id format is `{kind}-{datasetId}-{entityId}` (e.g.
+ * `figure-iala-2023-mixed-reflection`). Components, cross-ref click
+ * handlers, router guards, and prose mentions all use this module to
+ * compute or match anchor ids — keeping the scheme in one place means
+ * changing it later is a one-file edit.
+ *
+ * The kind prefix is the kind itself (e.g. `figure`), not a shortened
+ * alias. This matches the wire format and the anchor selector prefix
+ * used by the cross-ref composable.
+ */
+
+import type { NonVerbalKind } from '../adapters/non-verbal/types';
+
+const ANCHOR_KIND_PREFIX: Record<NonVerbalKind, string> = {
+  figure: 'figure',
+  table: 'table',
+  formula: 'formula',
+};
+
+export const ANCHOR_KIND_SELECTORS: readonly string[] = Object
+  .values(ANCHOR_KIND_PREFIX)
+  .map(k => `a[href^="#${k}-"]`);
+
+export function anchorId(kind: NonVerbalKind, datasetId: string, entityId: string): string {
+  return `${ANCHOR_KIND_PREFIX[kind]}-${datasetId}-${entityId}`;
+}
+
+export function anchorSelector(kind: NonVerbalKind, datasetId: string, entityId: string): string {
+  return `#${CSS.escape(anchorId(kind, datasetId, entityId))}`;
+}
+
+export interface ParsedAnchor {
+  kind: NonVerbalKind;
+  datasetId: string;
+  entityId: string;
+}
+
+const PARSER_RE = /^(figure|table|formula)-(.+)-(.+)$/;
+
+export function parseAnchorId(id: string): ParsedAnchor | null {
+  const m = id.match(PARSER_RE);
+  if (!m) return null;
+  return { kind: m[1] as NonVerbalKind, datasetId: m[2], entityId: m[3] };
+}
+
+export function hrefFromAnchor(id: string): string {
+  return `#${id}`;
+}

package/src/utils/non-verbal-highlight.ts

@@ -0,0 +1,27 @@
+/**
+ * Cross-reference highlight utility — shared by the click handler and the
+ * router scroll guard. Both call `highlightEntity()` after scrolling into
+ * view; the user sees a brief, accessible focus ring.
+ *
+ * Honors prefers-reduced-motion: the highlight class is added either way
+ * (it's a state indicator), but the smooth-scroll behavior is gated
+ * upstream by `useReducedMotion`.
+ */
+
+const HIGHLIGHT_CLASS = 'nv-entity--highlighted';
+const HIGHLIGHT_DURATION_MS = 1600;
+
+export function highlightEntity(el: HTMLElement | null): void {
+  if (!el) return;
+  el.classList.add(HIGHLIGHT_CLASS);
+  el.setAttribute('tabindex', '-1');
+  el.focus({ preventScroll: true });
+  window.setTimeout(() => {
+    el.classList.remove(HIGHLIGHT_CLASS);
+  }, HIGHLIGHT_DURATION_MS);
+}
+
+export function scrollToEntity(el: HTMLElement | null, smooth: boolean): void {
+  if (!el) return;
+  el.scrollIntoView({ behavior: smooth ? 'smooth' : 'auto', block: 'start' });
+}