@glossarist/concept-browser 0.7.43 → 0.7.45

package/src/components/table/TableMarkup.vue

@@ -0,0 +1,63 @@
+<script setup lang="ts">
+/**
+ * TableMarkup — renders a markup table (HTML / Markdown / AsciiDoc).
+ *
+ * The content is a LocalizedString — one markup string per locale. The
+ * renderer picks the locale via the SSOT, then applies the format-specific
+ * transform:
+ *   - `html`     → render as-is (sanitized by the DOMPurify-driven
+ *                  v-html trust boundary upstream — V1 trusts authored HTML)
+ *   - `markdown` → render via the lightweight markdown utility
+ *   - `asciidoc` → render via the lightweight asciidoc utility
+ */
+import { computed } from 'vue';
+import type { LocalizedString, TableFormat } from '../../adapters/non-verbal/types';
+import { pickLocaleMap } from '../../utils/locale';
+import { renderMarkdown } from '../../utils/markdown-lite';
+import { renderAsciiDocLite } from '../../utils/asciidoc-lite';
+
+const props = defineProps<{
+  content: LocalizedString;
+  format?: TableFormat;
+  locale: string;
+  fallbackChain?: readonly string[];
+}>();
+
+const resolved = computed(() => pickLocaleMap(props.content, props.locale, props.fallbackChain));
+
+const html = computed(() => {
+  const r = resolved.value;
+  if (!r) return '';
+  const fmt = props.format ?? 'html';
+  if (fmt === 'markdown') return renderMarkdown(r.text);
+  if (fmt === 'asciidoc') return renderAsciiDocLite(r.text);
+  return r.text;
+});
+
+const lang = computed(() => resolved.value?.locale);
+</script>
+
+<template>
+  <div class="nv-table nv-table--markup" :lang="lang" v-html="html"></div>
+</template>
+
+<style scoped>
+.nv-table {
+  width: 100%;
+  overflow-x: auto;
+  font-size: 0.875rem;
+}
+.nv-table :deep(table) {
+  width: 100%;
+  border-collapse: collapse;
+}
+.nv-table :deep(th),
+.nv-table :deep(td) {
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--ink-100, #e5e5e5);
+}
+.nv-table :deep(th) {
+  background: var(--surface-alt, #f5f5f5);
+  font-weight: 600;
+}
+</style>

package/src/components/table/TableStructured.vue

@@ -0,0 +1,66 @@
+<script setup lang="ts">
+/**
+ * TableStructured — renders a structured table (headers + rows).
+ *
+ * Each cell is a LocalizedString. Headers are LocalizedString[] and rows
+ * are LocalizedString[][]. The locale SSOT picks one language per cell —
+ * cells can fall back to English independently.
+ */
+import { computed } from 'vue';
+import type { LocalizedString } from '../../adapters/non-verbal/types';
+import { pickLocaleText } from '../../utils/locale';
+
+interface StructuredContent {
+  kind: 'structured';
+  headers: LocalizedString[];
+  rows: LocalizedString[][];
+}
+
+const props = defineProps<{
+  content: StructuredContent;
+  locale: string;
+  fallbackChain?: readonly string[];
+}>();
+
+const headerTexts = computed(() =>
+  props.content.headers.map(h => pickLocaleText(h, props.locale, props.fallbackChain)),
+);
+
+const rowTexts = computed(() =>
+  props.content.rows.map(r =>
+    r.map(cell => pickLocaleText(cell, props.locale, props.fallbackChain)),
+  ),
+);
+</script>
+
+<template>
+  <table class="nv-table nv-table--structured">
+    <thead v-if="headerTexts.length">
+      <tr>
+        <th v-for="(h, i) in headerTexts" :key="i" scope="col">{{ h }}</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr v-for="(row, ri) in rowTexts" :key="ri">
+        <td v-for="(cell, ci) in row" :key="ci">{{ cell }}</td>
+      </tr>
+    </tbody>
+  </table>
+</template>
+
+<style scoped>
+.nv-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.875rem;
+}
+.nv-table th, .nv-table td {
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--ink-100, #e5e5e5);
+  text-align: left;
+}
+.nv-table th {
+  background: var(--surface-alt, #f5f5f5);
+  font-weight: 600;
+}
+</style>

package/src/composables/use-concept-entities.ts

@@ -0,0 +1,70 @@
+/**
+ * useConceptEntities — pulls the structural non-verbal entity refs
+ * (`figures`, `tables`, `formulas`) from a Concept model instance and
+ * projects them into a uniform `{ kind, entityId, display }` shape that
+ * the list component can render without knowing about each kind.
+ *
+ * Per plan 02: structural refs live on `ManagedConceptData` (concept
+ * level), not on `LocalizedConcept`. The Concept model owns the raw
+ * arrays and the lazy getters that materialize them — this composable
+ * is a pure projection layer, not a source of truth.
+ *
+ * MECE: this composable reads; it does not fetch (the resolver does),
+ * does not render (the component does), and does not own the wire
+ * format (the bridge does).
+ */
+import { computed, type ComputedRef } from 'vue';
+import type { Concept } from 'glossarist';
+import type { NonVerbalKind } from '../adapters/non-verbal/types';
+import { anchorId } from '../utils/non-verbal-anchor';
+
+export interface StructuralEntityRef {
+  kind: NonVerbalKind;
+  entityId: string;
+  display: string | null;
+  anchor: string;
+}
+
+const KIND_TO_CONCEPT_FIELD: Readonly<Record<NonVerbalKind, 'figures' | 'tables' | 'formulas'>> = {
+  figure: 'figures',
+  table: 'tables',
+  formula: 'formulas',
+};
+
+/**
+ * glossarist-js's published `.d.ts` omits Concept's lazy getters for
+ * structural refs (`figures`, `tables`, `formulas`), but the runtime
+ * exposes them per TODO.figures/02. Cast through `unknown` once at
+ * this boundary so consumers see a typed shape.
+ */
+interface ConceptWithEntityRefs {
+  readonly figures: ReadonlyArray<{ entityId: string | null; display: string | null }>;
+  readonly tables: ReadonlyArray<{ entityId: string | null; display: string | null }>;
+  readonly formulas: ReadonlyArray<{ entityId: string | null; display: string | null }>;
+}
+
+export function useConceptEntities(
+  concept: ComputedRef<Concept>,
+  datasetId: ComputedRef<string>,
+): ComputedRef<StructuralEntityRef[]> {
+  return computed(() => {
+    const ds = datasetId.value;
+    const c = concept.value as unknown as ConceptWithEntityRefs;
+    const out: StructuralEntityRef[] = [];
+    for (const kind of Object.keys(KIND_TO_CONCEPT_FIELD) as NonVerbalKind[]) {
+      const refs = c[KIND_TO_CONCEPT_FIELD[kind]];
+      if (!refs || refs.length === 0) continue;
+      for (const r of refs) {
+        const entityId = r.entityId;
+        if (!entityId) continue;
+        out.push({
+          kind,
+          entityId,
+          display: r.display ?? null,
+          anchor: anchorId(kind, ds, entityId),
+        });
+      }
+    }
+    return out;
+  });
+}

package/src/composables/use-non-verbal-cross-ref.ts

@@ -0,0 +1,79 @@
+/**
+ * useNonVerbalCrossRef — wires renderer-emitted entity anchors
+ * (`<a href="#figure-{ds}-{id}">`) to in-page scroll, highlight, focus,
+ * and URL-hash update.
+ *
+ * Why a delegated document-level click handler? Entity references are
+ * rendered into `v-html` by the content-renderer; Vue `@click` does
+ * not bind to children of `v-html`. A single capture-phase handler on
+ * `document` is the correct pattern, and it stays in one place
+ * regardless of how many mentions the page contains.
+ *
+ * The behavior is identical across figure/table/formula — only the
+ * anchor prefix differs. `ANCHOR_KIND_SELECTORS` (from the anchor SSOT)
+ * is the single source for which prefixes count.
+ */
+import { onMounted, onBeforeUnmount } from 'vue';
+import { useReducedMotion } from './use-reduced-motion';
+import { ANCHOR_KIND_SELECTORS } from '../utils/non-verbal-anchor';
+import { highlightEntity, scrollToEntity } from '../utils/non-verbal-highlight';
+
+const ENTITY_LINK_SELECTOR = ANCHOR_KIND_SELECTORS.join(', ');
+
+export interface NonVerbalCrossRefOptions {
+  /** Override the document (injectable for tests). */
+  document?: Document;
+  /** Override the history API (injectable for tests). */
+  history?: History;
+}
+
+export interface NonVerbalCrossRef {
+  /** Programmatically activate an entity (e.g. from a list click). */
+  navigateToEntity: (anchorId: string) => void;
+}
+
+export function useNonVerbalCrossRef(
+  opts: NonVerbalCrossRefOptions = {},
+): NonVerbalCrossRef {
+  const doc = opts.document ?? (typeof document !== 'undefined' ? document : null);
+  const hist = opts.history ?? (typeof history !== 'undefined' ? history : null);
+  const reducedMotion = useReducedMotion();
+
+  function onGlobalClick(event: MouseEvent): void {
+    if (!doc) return;
+    const target = (event.target as HTMLElement | null)?.closest<HTMLAnchorElement>(
+      ENTITY_LINK_SELECTOR,
+    );
+    if (!target) return;
+    const href = target.getAttribute('href') ?? '';
+    if (!href.startsWith('#')) return;
+    const anchorId = href.slice(1);
+    const el = doc.getElementById(anchorId);
+    if (!el) return;
+    event.preventDefault();
+    activate(el, anchorId);
+  }
+
+  function activate(el: HTMLElement, anchorId: string): void {
+    scrollToEntity(el, !reducedMotion.value);
+    highlightEntity(el);
+    if (hist && doc && doc.location.hash !== `#${anchorId}`) {
+      hist.pushState(null, '', `#${anchorId}`);
+    }
+  }
+
+  function navigateToEntity(anchorId: string): void {
+    const el = doc?.getElementById(anchorId);
+    if (!el) return;
+    activate(el, anchorId);
+  }
+
+  onMounted(() => {
+    doc?.addEventListener('click', onGlobalClick, { capture: true });
+  });
+  onBeforeUnmount(() => {
+    doc?.removeEventListener('click', onGlobalClick);
+  });
+
+  return { navigateToEntity };
+}

package/src/composables/use-non-verbal-entity.ts

@@ -0,0 +1,58 @@
+/**
+ * useNonVerbalEntity — composable that fetches one non-verbal entity
+ * through the resolver and tracks loading / not-found / error state.
+ *
+ * Components call this; they never touch `fetch()` directly. Locale is
+ * reactive — changing it does NOT refetch (the resolver caches the raw
+ * JSON-LD; localization happens at render time via the locale SSOT).
+ */
+import { ref, watch, shallowRef } from 'vue';
+import { getFactory } from '../adapters/factory';
+import type { NonVerbalEntity, NonVerbalKind } from '../adapters/non-verbal/types';
+
+export type LoadState = 'loading' | 'loaded' | 'not-found' | 'error';
+
+export interface UseNonVerbalEntityOptions {
+  immediate?: boolean;
+}
+
+export function useNonVerbalEntity(
+  kind: () => NonVerbalKind,
+  datasetId: () => string,
+  entityId: () => string,
+  _opts: UseNonVerbalEntityOptions = {},
+) {
+  const entity = shallowRef<NonVerbalEntity | null>(null);
+  const state = ref<LoadState>('loading');
+  const error = ref<string | null>(null);
+
+  async function load() {
+    const k = kind();
+    const ds = datasetId();
+    const id = entityId();
+    if (!k || !ds || !id) {
+      state.value = 'not-found';
+      entity.value = null;
+      return;
+    }
+    state.value = 'loading';
+    error.value = null;
+    try {
+      const e = await getFactory().nonVerbalResolver.resolve(k, ds, id);
+      entity.value = e;
+      state.value = e ? 'loaded' : 'not-found';
+    } catch (err) {
+      state.value = 'error';
+      error.value = err instanceof Error ? err.message : String(err);
+      entity.value = null;
+    }
+  }
+
+  watch(
+    [kind, datasetId, entityId],
+    () => { void load(); },
+    { immediate: true },
+  );
+
+  return { entity, state, error, reload: load };
+}

package/src/composables/use-reduced-motion.ts

@@ -0,0 +1,26 @@
+/**
+ * Generic reduced-motion watcher. Shared across feature modules that need
+ * to respect the user's `prefers-reduced-motion` setting.
+ */
+import { ref, onMounted, onBeforeUnmount } from 'vue';
+
+export function useReducedMotion() {
+  const reduced = ref(false);
+  let mql: MediaQueryList | null = null;
+
+  const handler = (e: MediaQueryListEvent) => { reduced.value = e.matches; };
+
+  onMounted(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return;
+    mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+    reduced.value = mql.matches;
+    mql.addEventListener('change', handler);
+  });
+
+  onBeforeUnmount(() => {
+    if (mql) mql.removeEventListener('change', handler);
+    mql = null;
+  });
+
+  return reduced;
+}

package/src/composables/use-render-options.ts

@@ -1,55 +1,52 @@
-import { ref, watch } from 'vue';
-import type { RenderOptions, BibResolver, FigResolver } from '../utils/content-renderer';
+import { ref } from 'vue';
+import type { RenderOptions, BibResolver, NonVerbalRefResolver } from '../utils/content-renderer';
+import type { NonVerbalKind } from '../adapters/non-verbal/types';
 import { getFactory } from '../adapters/factory';
+import { anchorId } from '../utils/non-verbal-anchor';
 import { escapeAttr } from '../utils/escape';
 
-interface BibEntry {
-  reference: string;
-  title?: string;
-  link?: string;
-}
-
-const bibCache = new Map<string, Record<string, BibEntry>>();
-
-async function loadBibliography(registerId: string): Promise<Record<string, BibEntry> | null> {
-  if (bibCache.has(registerId)) return bibCache.get(registerId)!;
-  try {
-    const resp = await fetch(`${import.meta.env.BASE_URL}data/${registerId}/bibliography.json`);
-    if (!resp.ok) return null;
-    const data = await resp.json();
-    bibCache.set(registerId, data);
-    return data;
-  } catch {
-    return null;
-  }
-}
-
 export function useRenderOptions(registerId: () => string) {
-  const bibData = ref<Record<string, BibEntry> | null>(null);
+  const ready = ref(false);
 
   async function ensureBibLoaded() {
     const id = registerId();
     if (!id) return;
-    bibData.value = await loadBibliography(id);
+    await getFactory().bibliography(id).load();
+    ready.value = true;
   }
 
   const bibResolver: BibResolver = (refId, title) => {
-    const entry = bibData.value?.[refId];
+    const id = registerId();
+    const entry = id ? getFactory().bibliography(id).findById(refId) : null;
     if (!entry) {
       return `<span class="bib-ref">${escapeAttr(title)}</span>`;
     }
-    const display = title || entry.reference;
+    const display = title || entry.reference || refId;
     if (entry.link) {
-      return `<a href="${escapeAttr(entry.link)}" target="_blank" rel="noopener" class="bib-link" title="${escapeAttr(entry.title || '')}">${escapeAttr(display)}</a>`;
+      return `<a href="${escapeAttr(entry.link)}" target="_blank" rel="noopener" class="bib-link" title="${escapeAttr(entry.title ?? '')}">${escapeAttr(display)}</a>`;
     }
-    return `<span class="bib-ref" title="${escapeAttr(entry.title || '')}">${escapeAttr(display)}</span>`;
+    return `<span class="bib-ref" title="${escapeAttr(entry.title ?? '')}">${escapeAttr(display)}</span>`;
   };
 
-  const figResolver: FigResolver = (figId) => {
+  const nonVerbalRefResolver: NonVerbalRefResolver = (kind: NonVerbalKind, entityId, display) => {
     const id = registerId();
-    const imgSrc = `${import.meta.env.BASE_URL}data/${id}/images/${figId}.png`;
-    return `<span class="fig-ref"><a href="${escapeAttr(imgSrc)}" target="_blank" rel="noopener">${escapeAttr(figId)}</a></span>`;
+    if (!id) {
+      const label = display ?? entityId;
+      return `<span class="nv-ref nv-ref--${kind}">${escapeAttr(label)}</span>`;
+    }
+    const href = `#${anchorId(kind, id, entityId)}`;
+    const label = display ?? defaultLabelForKind(kind, entityId);
+    const cls = `nv-ref nv-ref--${kind}`;
+    return `<a href="${href}" class="${cls}" data-nv-kind="${escapeAttr(kind)}" data-nv-dataset="${escapeAttr(id)}" data-nv-entity="${escapeAttr(entityId)}">${escapeAttr(label)}</a>`;
   };
 
-  return { bibData, ensureBibLoaded, bibResolver, figResolver };
+  return { ready, ensureBibLoaded, bibResolver, nonVerbalRefResolver };
+}
+
+function defaultLabelForKind(kind: NonVerbalKind, entityId: string): string {
+  switch (kind) {
+    case 'figure': return `Figure ${entityId}`;
+    case 'table': return `Table ${entityId}`;
+    case 'formula': return `Formula ${entityId}`;
+  }
 }

package/src/router/index.ts

@@ -1,4 +1,5 @@
 import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';
+import { installNonVerbalScroll } from './non-verbal-scroll-guard';
 
 export const routes: RouteRecordRaw[] = [
   {
@@ -109,4 +110,6 @@ const router = createRouter({
   routes,
 });
 
+installNonVerbalScroll(router);
+
 export default router;

package/src/router/non-verbal-scroll-guard.ts

@@ -0,0 +1,56 @@
+/**
+ * installNonVerbalScroll — router hook that turns entity-hash deep-links
+ * (`/concept/X#figure-{ds}-{id}`) into scroll + highlight on arrival.
+ *
+ * Why polling instead of an event? Entity components fetch their
+ * JSON-LD asynchronously via the resolver; the target `<figure>` does
+ * not exist in the DOM until that fetch resolves. Polling for up to
+ * `timeoutMs` covers the slow-network worst case without coupling the
+ * router to the resolver.
+ *
+ * The anchor id format is owned by `utils/non-verbal-anchor.ts`; this
+ * guard only matches the hash prefix and hands off to the same
+ * highlight utility used by click-driven navigation, so the user sees
+ * identical behavior whether they arrived by click or by URL.
+ */
+import type { Router } from 'vue-router';
+import { highlightEntity, scrollToEntity } from '../utils/non-verbal-highlight';
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const POLL_INTERVAL_MS = 50;
+
+const ENTITY_HASH_RE = /^#(?:figure|table|formula)-/;
+
+export function installNonVerbalScroll(
+  router: Router,
+  options: { timeoutMs?: number } = {},
+): void {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  router.afterEach((to) => {
+    if (!to.hash || !ENTITY_HASH_RE.test(to.hash)) return;
+    const anchorId = to.hash.slice(1);
+    const prefersReducedMotion = typeof window !== 'undefined'
+      && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+
+    void waitForElement(anchorId, timeoutMs).then((el) => {
+      if (!el) return;
+      scrollToEntity(el, !prefersReducedMotion);
+      highlightEntity(el);
+    });
+  });
+}
+
+function waitForElement(id: string, timeoutMs: number): Promise<HTMLElement | null> {
+  return new Promise((resolve) => {
+    if (typeof document === 'undefined') return resolve(null);
+    const start = Date.now();
+    const tick = () => {
+      const el = document.getElementById(id);
+      if (el) return resolve(el);
+      if (Date.now() - start > timeoutMs) return resolve(null);
+      setTimeout(tick, POLL_INTERVAL_MS);
+    };
+    tick();
+  });
+}

package/src/style.css

@@ -133,6 +133,23 @@
     @apply text-ink-600 hover:text-ink-800 underline-offset-2 hover:underline transition-colors;
   }
 
+  /* Non-verbal entity highlight — single source of truth for the
+     cross-ref "you landed here" affordance. Toggled by
+     utils/non-verbal-highlight.ts; applies to figure/table/formula
+     root elements uniformly. */
+  .nv-entity--highlighted {
+    outline: 2px solid var(--brand-primary, #2563eb);
+    outline-offset: 4px;
+    animation: nv-entity-pulse 1.6s ease-out;
+  }
+  @keyframes nv-entity-pulse {
+    0%, 100% { box-shadow: 0 0 0 0 rgba(37, 99, 235, 0); }
+    20%      { box-shadow: 0 0 0 6px rgba(37, 99, 235, 0.25); }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .nv-entity--highlighted { animation: none; }
+  }
+
   /* Concept definition lists */
   .concept-list {
     list-style: disc;