@glossarist/concept-browser 0.7.44 → 0.7.46

package/src/components/non-verbal/NonVerbalList.vue

@@ -0,0 +1,118 @@
+<script setup lang="ts">
+/**
+ * NonVerbalList — renders the structural non-verbal entity refs
+ * (`figures[]`, `tables[]`, `formulas[]` from the concept) as a compact
+ * list of in-page anchor links.
+ *
+ * This is the "Figures / Tables / Formulas" section of a concept page.
+ * Inline mentions in prose are handled separately by the content
+ * renderer; this list surfaces entities the author declared as
+ * structural members of the concept regardless of whether they are
+ * also mentioned inline.
+ *
+ * Click handling is delegated to `useNonVerbalCrossRef` (a single
+ * document-level handler), so the links here are plain `<a href="#…">`.
+ */
+import { computed } from 'vue';
+import type { StructuralEntityRef } from '../../composables/use-concept-entities';
+import type { NonVerbalKind } from '../../adapters/non-verbal/types';
+
+const props = defineProps<{
+  refs: StructuralEntityRef[];
+}>();
+
+const KIND_LABEL: Readonly<Record<NonVerbalKind, string>> = {
+  figure: 'Figure',
+  table: 'Table',
+  formula: 'Formula',
+};
+
+const KIND_BADGE_CLASS: Readonly<Record<NonVerbalKind, string>> = {
+  figure: 'bg-violet-50 text-violet-700',
+  table: 'bg-sky-50 text-sky-700',
+  formula: 'bg-amber-50 text-amber-700',
+};
+
+interface GroupedRefs {
+  kind: NonVerbalKind;
+  label: string;
+  badgeClass: string;
+  items: StructuralEntityRef[];
+}
+
+const grouped = computed<GroupedRefs[]>(() => {
+  const map = new Map<NonVerbalKind, StructuralEntityRef[]>();
+  for (const r of props.refs) {
+    const bucket = map.get(r.kind) ?? [];
+    bucket.push(r);
+    map.set(r.kind, bucket);
+  }
+  const out: GroupedRefs[] = [];
+  for (const [kind, items] of map) {
+    out.push({
+      kind,
+      label: KIND_LABEL[kind],
+      badgeClass: KIND_BADGE_CLASS[kind],
+      items,
+    });
+  }
+  return out;
+});
+
+function labelOf(r: StructuralEntityRef): string {
+  return r.display ?? r.entityId;
+}
+</script>
+
+<template>
+  <div v-if="refs.length" class="space-y-3">
+    <div class="section-label">Non-verbal entities</div>
+    <div
+      v-for="group in grouped"
+      :key="group.kind"
+      class="card p-3 space-y-1.5"
+    >
+      <div class="flex items-center gap-2">
+        <span class="badge text-[10px]" :class="group.badgeClass">{{ group.label }}s</span>
+        <span class="text-xs text-ink-400">{{ group.items.length }}</span>
+      </div>
+      <ol class="space-y-1">
+        <li v-for="r in group.items" :key="r.anchor">
+          <a
+            :href="`#${r.anchor}`"
+            class="nv-list__link"
+          >
+            <span class="nv-list__label">{{ labelOf(r) }}</span>
+            <span v-if="r.display" class="nv-list__id">{{ r.entityId }}</span>
+          </a>
+        </li>
+      </ol>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.nv-list__link {
+  display: flex;
+  align-items: baseline;
+  gap: 0.5rem;
+  padding: 0.25rem 0.375rem;
+  border-radius: 0.25rem;
+  font-size: 0.8125rem;
+  color: var(--ink-700, #444);
+  text-decoration: none;
+  transition: background-color 120ms ease;
+}
+.nv-list__link:hover {
+  background: var(--ink-50, #f5f5f5);
+  color: var(--ink-900, #111);
+}
+.nv-list__label {
+  font-weight: 500;
+}
+.nv-list__id {
+  font-family: 'JetBrains Mono', monospace;
+  font-size: 0.6875rem;
+  color: var(--ink-400, #888);
+}
+</style>

package/src/components/non-verbal/NonVerbalSources.vue

@@ -0,0 +1,61 @@
+<script setup lang="ts">
+/**
+ * NonVerbalSources — shared source list for all three entity kinds.
+ *
+ * Reuses the existing CitationDisplay component for individual citations
+ * so the rendering matches the rest of the app. Each source may carry a
+ * modification note (e.g. "Adapted.") which is rendered alongside.
+ */
+import type { Citation } from 'glossarist';
+import type { NonVerbalSource } from '../../adapters/non-verbal/types';
+import CitationDisplay from '../CitationDisplay.vue';
+
+defineProps<{
+  sources: NonVerbalSource[];
+}>();
+
+// CitationDisplay expects glossarist's Citation class. NonVerbalSource.origin
+// is wire-compatible at runtime but typed differently on the consumer side;
+// cast once at this boundary.
+function asCitation(origin: NonVerbalSource['origin']): Citation | null {
+  return (origin as unknown as Citation) ?? null;
+}
+</script>
+
+<template>
+  <div v-if="sources.length" class="nv-sources">
+    <div class="nv-sources__label">Sources</div>
+    <ol class="nv-sources__list">
+      <li v-for="(src, i) in sources" :key="i" class="nv-source">
+        <CitationDisplay v-if="asCitation(src.origin)" :citation="asCitation(src.origin)!" />
+        <span v-if="src.modification" class="nv-source__modification">
+          — {{ src.modification }}
+        </span>
+      </li>
+    </ol>
+  </div>
+</template>
+
+<style scoped>
+.nv-sources {
+  font-size: 0.75rem;
+  color: var(--ink-500, #666);
+  margin-top: 0.5rem;
+}
+.nv-sources__label {
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  margin-bottom: 0.25rem;
+}
+.nv-sources__list {
+  list-style: decimal inside;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+.nv-source__modification {
+  color: var(--ink-400, #888);
+  font-style: italic;
+}
+</style>

package/src/components/table/TableDisplay.vue

@@ -0,0 +1,99 @@
+<script setup lang="ts">
+/**
+ * TableDisplay — renders a dataset-level Table entity.
+ *
+ * Delegates content rendering to TableStructured (headers + rows) or
+ * TableMarkup (HTML / Markdown / AsciiDoc) based on `content.kind`.
+ */
+import { computed } from 'vue';
+import type { Table } from '../../adapters/non-verbal/types';
+import { useNonVerbalEntity } from '../../composables/use-non-verbal-entity';
+import { resolveFallbackChain } from '../../utils/locale';
+import { anchorId } from '../../utils/non-verbal-anchor';
+import NonVerbalCaption from '../non-verbal/NonVerbalCaption.vue';
+import NonVerbalSources from '../non-verbal/NonVerbalSources.vue';
+import NonVerbalFallback from '../non-verbal/NonVerbalFallback.vue';
+import TableStructured from './TableStructured.vue';
+import TableMarkup from './TableMarkup.vue';
+
+const props = defineProps<{
+  datasetId: string;
+  entityId: string;
+  locale: string;
+  datasetLocales?: readonly string[];
+}>();
+
+const k = () => 'table' as const;
+const { entity, state, error } = useNonVerbalEntity(k, () => props.datasetId, () => props.entityId);
+
+const fallbackChain = computed(() => resolveFallbackChain(props.datasetLocales));
+const anchor = computed(() => anchorId('table', props.datasetId, props.entityId));
+const descriptionId = computed(() => `${anchor.value}-desc`);
+
+const table = computed<Table | null>(() => entity.value as Table | null);
+const structuredContent = computed(() => {
+  const c = table.value?.content;
+  return c && c.kind === 'structured' ? c : null;
+});
+const markup = computed(() => {
+  const c = table.value?.content;
+  return c && c.kind === 'markup' ? c.markup : null;
+});
+</script>
+
+<template>
+  <figure
+    v-if="table && state === 'loaded'"
+    :id="anchor"
+    class="table-entity"
+  >
+    <TableStructured
+      v-if="structuredContent"
+      :content="structuredContent"
+      :locale="locale"
+      :fallback-chain="fallbackChain"
+    />
+    <TableMarkup
+      v-else-if="markup"
+      :content="markup"
+      :format="table.format"
+      :locale="locale"
+      :fallback-chain="fallbackChain"
+    />
+
+    <NonVerbalCaption
+      :identifier="table.identifier"
+      :caption="table.caption"
+      :description="table.description"
+      :locale="locale"
+      :fallback-chain="fallbackChain"
+      :description-id="descriptionId"
+    />
+
+    <NonVerbalSources
+      v-if="table.sources?.length"
+      :sources="table.sources"
+    />
+  </figure>
+
+  <NonVerbalFallback
+    v-else-if="state === 'loading' || state === 'not-found' || state === 'error'"
+    :state="state"
+    kind="table"
+    :entity-id="entityId"
+    :message="error ?? undefined"
+  />
+</template>
+
+<style scoped>
+.table-entity {
+  margin: 1rem 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.table-entity:focus-visible {
+  outline: 2px solid var(--blue-500, #3b82f6);
+  outline-offset: 4px;
+}
+</style>

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;
+}