@glossarist/concept-browser 0.7.43 → 0.7.45

package/src/components/figure/figure-image-pick.ts

@@ -0,0 +1,56 @@
+/**
+ * Figure image picker — single SSOT for choosing the best variant from
+ * a Figure's image array.
+ *
+ * Decision order:
+ *   1. If user prefers dark color scheme and a dark variant exists, use it.
+ *   2. If user prefers light color scheme and a light variant exists, use it.
+ *   3. If a vector (SVG) variant exists and the user prefers vector, use it.
+ *   4. Otherwise, fall back to the first declared variant.
+ *
+ * The `print` role is reserved for print stylesheets (selected via CSS
+ * @media print in FigureImages.vue), not picked here.
+ */
+import type { FigureImage } from '../../adapters/non-verbal/types';
+
+export interface PickOptions {
+  prefersDark?: boolean;
+  prefersVector?: boolean;
+}
+
+export function pickBestImage(images: FigureImage[], opts: PickOptions = {}): FigureImage | null {
+  if (images.length === 0) return null;
+  if (opts.prefersDark) {
+    const dark = images.find(i => i.role === 'dark');
+    if (dark) return dark;
+  }
+  if (!opts.prefersDark) {
+    const light = images.find(i => i.role === 'light');
+    if (light) return light;
+  }
+  if (opts.prefersVector) {
+    const vector = images.find(i => i.format === 'svg' || i.role === 'vector');
+    if (vector) return vector;
+  }
+  return images[0] ?? null;
+}
+
+/**
+ * Group image variants by role for the <picture> element. Returns the
+ * responsive sources in the order they should appear (most-specific
+ * first), plus the default `<img>` source.
+ */
+export function groupImageVariants(images: FigureImage[]): {
+  sources: FigureImage[];
+  img: FigureImage | null;
+  print: FigureImage | null;
+} {
+  const print = images.find(i => i.role === 'print') ?? null;
+  const dark = images.find(i => i.role === 'dark');
+  const light = images.find(i => i.role === 'light');
+  const sources: FigureImage[] = [];
+  if (dark) sources.push(dark);
+  if (light) sources.push(light);
+  const img = pickBestImage(images, {}) ?? images[0] ?? null;
+  return { sources, img, print };
+}

package/src/components/figure/figure-layout.ts

@@ -0,0 +1,26 @@
+/**
+ * Figure layout derivation — derives a layout label from subfigure count.
+ *
+ * Per the architectural rule "derive layout, don't store it", this helper
+ * inspects a Figure's subfigures and returns the layout kind:
+ *
+ *   - `single`  — no subfigures
+ *   - `row`     — 2 subfigures side-by-side
+ *   - `column`  — 3+ subfigures in a vertical stack (default for many)
+ *   - `grid`    — 4+ subfigures in a 2-col grid
+ *
+ * Authors who want different behavior can split a composite figure into
+ * multiple top-level figures. V1 does not expose a `layout` field.
+ */
+import type { Figure } from '../../adapters/non-verbal/types';
+
+export type FigureLayout = 'single' | 'row' | 'column' | 'grid';
+
+export function deriveLayout(fig: Figure): FigureLayout {
+  const count = fig.subfigures?.length ?? 0;
+  if (count === 0) return 'single';
+  if (count === 1) return 'column';
+  if (count === 2) return 'row';
+  if (count === 3) return 'column';
+  return 'grid';
+}

package/src/components/formula/FormulaDisplay.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+/**
+ * FormulaDisplay — renders a dataset-level Formula entity.
+ *
+ * Caption + expression + description + sources. The expression renders
+ * via Plurimath (LaTeX/MathML/AsciiMath). Self-anchoring — the outer
+ * `<figure>` receives the anchor ID for `{{formula:id}}` mentions.
+ */
+import { computed } from 'vue';
+import type { Formula } 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 FormulaExpression from './FormulaExpression.vue';
+
+const props = defineProps<{
+  datasetId: string;
+  entityId: string;
+  locale: string;
+  datasetLocales?: readonly string[];
+}>();
+
+const k = () => 'formula' as const;
+const { entity, state, error } = useNonVerbalEntity(k, () => props.datasetId, () => props.entityId);
+
+const fallbackChain = computed(() => resolveFallbackChain(props.datasetLocales));
+const anchor = computed(() => anchorId('formula', props.datasetId, props.entityId));
+const descriptionId = computed(() => `${anchor.value}-desc`);
+</script>
+
+<template>
+  <figure
+    v-if="entity && state === 'loaded'"
+    :id="anchor"
+    class="formula-entity"
+  >
+    <div class="formula__expr-line">
+      <FormulaExpression
+        :expression="(entity as Formula).expression"
+        :notation="(entity as Formula).notation"
+        :locale="locale"
+        :fallback-chain="fallbackChain"
+      />
+    </div>
+
+    <NonVerbalCaption
+      :identifier="(entity as Formula).identifier"
+      :caption="(entity as Formula).caption"
+      :description="(entity as Formula).description"
+      :locale="locale"
+      :fallback-chain="fallbackChain"
+      :description-id="descriptionId"
+    />
+
+    <NonVerbalSources
+      v-if="(entity as Formula).sources?.length"
+      :sources="(entity as Formula).sources!"
+    />
+  </figure>
+
+  <NonVerbalFallback
+    v-else-if="state === 'loading' || state === 'not-found' || state === 'error'"
+    :state="state"
+    kind="formula"
+    :entity-id="entityId"
+    :message="error ?? undefined"
+  />
+</template>
+
+<style scoped>
+.formula-entity {
+  margin: 1rem 0;
+  padding: 0.75rem 1rem;
+  border-left: 3px solid var(--ink-200, #e5e5e5);
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.formula__expr-line {
+  font-size: 1.125rem;
+  padding: 0.25rem 0;
+}
+.formula-entity:focus-visible {
+  outline: 2px solid var(--blue-500, #3b82f6);
+  outline-offset: 4px;
+}
+</style>

package/src/components/formula/FormulaExpression.vue

@@ -0,0 +1,70 @@
+<script setup lang="ts">
+/**
+ * FormulaExpression — renders one formula expression in its notation.
+ *
+ * Uses Plurimath (the project's existing math library, NOT KaTeX) to
+ * render LaTeX / AsciiMath / MathML to MathML+HTML. Plurimath output
+ * includes semantic MathML for screen readers as a by-product of its
+ * internal pipeline, so no extra a11y work is needed.
+ *
+ * The expression is a LocalizedString — different locales can name
+ * variables in their local language while keeping the same notation type.
+ */
+import { computed, ref, watch, onMounted } from 'vue';
+import type { LocalizedString, FormulaNotation } from '../../adapters/non-verbal/types';
+import { pickLocaleMap, localeToBcp47 } from '../../utils/locale';
+import { loadPlurimath } from '../../utils/plurimath';
+
+const props = defineProps<{
+  expression: LocalizedString;
+  notation: FormulaNotation;
+  locale: string;
+  fallbackChain?: readonly string[];
+}>();
+
+const resolved = computed(() => pickLocaleMap(props.expression, props.locale, props.fallbackChain));
+const html = ref<string>('');
+const lang = computed(() => resolved.value ? localeToBcp47(resolved.value.locale) : undefined);
+
+const PLURIMATH_FORMAT: Record<FormulaNotation, string> = {
+  latex: 'latex',
+  asciimath: 'asciimath',
+  mathml: 'mathml',
+};
+
+async function render() {
+  const r = resolved.value;
+  if (!r) { html.value = ''; return; }
+  try {
+    const Plurimath = await loadPlurimath();
+    const p = new Plurimath(r.text, PLURIMATH_FORMAT[props.notation]);
+    html.value = p.toMathml().replace('display="block"', 'display="inline"').trim();
+  } catch {
+    html.value = `<code class="formula-fallback">${r.text}</code>`;
+  }
+}
+
+onMounted(render);
+watch([resolved, () => props.notation], render);
+</script>
+
+<template>
+  <span class="formula__expression" :lang="lang">
+    <span v-if="html" v-html="html"></span>
+    <code v-else></code>
+  </span>
+</template>
+
+<style scoped>
+.formula__expression {
+  display: inline-block;
+  font-family: 'Latin Modern Math', 'STIX Two Math', serif;
+}
+.formula-fallback {
+  font-family: var(--font-mono, monospace);
+  background: var(--surface-alt, #f5f5f5);
+  padding: 0.125rem 0.375rem;
+  border-radius: 0.25rem;
+  font-size: 0.875rem;
+}
+</style>

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

@@ -0,0 +1,104 @@
+<script setup lang="ts">
+/**
+ * NonVerbalCaption — shared caption + identifier + description.
+ *
+ * Renders identically for Figure, Table, Formula. The shape:
+ *
+ *   <figcaption>
+ *     <span class="nv-caption__identifier">Figure 7c.</span>
+ *     <span class="nv-caption__text" lang="en">Caption text.</span>
+ *     <details>
+ *       <summary>Detailed description</summary>
+ *       <p lang="en">Long description text.</p>
+ *     </details>
+ *   </figcaption>
+ *
+ * The `lang` attribute reflects the ACTUAL resolved locale (not the
+ * requested one), so a French page with an English-only caption shows
+ * `lang="en"` on the caption — correct for screen readers.
+ */
+import { computed } from 'vue';
+import type { LocalizedString } from '../../adapters/non-verbal/types';
+import { pickLocaleMap, localeToBcp47 } from '../../utils/locale';
+
+const props = defineProps<{
+  identifier?: string;
+  caption?: LocalizedString;
+  description?: LocalizedString;
+  locale: string;
+  fallbackChain?: readonly string[];
+  descriptionId?: string;
+}>();
+
+const captionResolved = computed(() =>
+  pickLocaleMap(props.caption, props.locale, props.fallbackChain),
+);
+
+const descriptionResolved = computed(() =>
+  pickLocaleMap(props.description, props.locale, props.fallbackChain),
+);
+
+const captionLang = computed(() =>
+  captionResolved.value ? localeToBcp47(captionResolved.value.locale) : undefined,
+);
+
+const descriptionLang = computed(() =>
+  descriptionResolved.value ? localeToBcp47(descriptionResolved.value.locale) : undefined,
+);
+</script>
+
+<template>
+  <figcaption class="nv-caption">
+    <span v-if="identifier" class="nv-caption__identifier">{{ identifier }}.</span>
+    <span
+      v-if="captionResolved"
+      class="nv-caption__text"
+      :lang="captionLang"
+    >{{ captionResolved.text }}</span>
+    <details
+      v-if="descriptionResolved"
+      :id="descriptionId"
+      class="nv-caption__desc"
+    >
+      <summary>Detailed description</summary>
+      <p :lang="descriptionLang">{{ descriptionResolved.text }}</p>
+    </details>
+  </figcaption>
+</template>
+
+<style scoped>
+.nv-caption {
+  font-size: 0.875rem;
+  color: var(--ink-700, #444);
+  line-height: 1.5;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+.nv-caption__identifier {
+  font-weight: 600;
+  color: var(--ink-800, #222);
+}
+.nv-caption__text {
+  font-style: italic;
+}
+.nv-caption__desc {
+  margin-top: 0.25rem;
+  font-size: 0.8125rem;
+  color: var(--ink-500, #666);
+}
+.nv-caption__desc > summary {
+  cursor: pointer;
+  font-weight: 500;
+  color: var(--ink-600, #555);
+}
+.nv-caption__desc > p {
+  margin-top: 0.5rem;
+  line-height: 1.6;
+}
+
+@media (prefers-contrast: more) {
+  .nv-caption__text { font-weight: 600; }
+  .nv-caption__identifier { font-weight: 700; }
+}
+</style>

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

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+/**
+ * NonVerbalFallback — shared loading / not-found / error state.
+ *
+ * Each entity display component renders its own fallback rather than
+ * hoisting errors to a global banner. Per the project rule
+ * "Error handling: local over global", a missing figure should not
+ * break the page — it shows a compact notice inline.
+ */
+defineProps<{
+  state: 'loading' | 'not-found' | 'error';
+  kind: 'figure' | 'table' | 'formula';
+  entityId: string;
+  message?: string;
+}>();
+</script>
+
+<template>
+  <div
+    class="nv-fallback"
+    :class="`nv-fallback--${state}`"
+    role="status"
+    :aria-live="state === 'error' ? 'assertive' : 'polite'"
+  >
+    <template v-if="state === 'loading'">
+      <span class="nv-fallback__spinner" aria-hidden="true"></span>
+      Loading {{ kind }} <code>{{ entityId }}</code>…
+    </template>
+    <template v-else-if="state === 'not-found'">
+      {{ kind }} <code>{{ entityId }}</code> not found
+    </template>
+    <template v-else>
+      Failed to load {{ kind }} <code>{{ entityId }}</code>
+      <span v-if="message" class="nv-fallback__detail">: {{ message }}</span>
+    </template>
+  </div>
+</template>
+
+<style scoped>
+.nv-fallback {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  border-radius: 0.375rem;
+  font-size: 0.8125rem;
+  color: var(--ink-500, #666);
+  background: var(--surface-alt, #f5f5f5);
+  border: 1px dashed var(--ink-200, #ccc);
+}
+.nv-fallback--error {
+  color: #b91c1c;
+  background: #fef2f2;
+  border-color: #fecaca;
+}
+.nv-fallback__spinner {
+  width: 0.75rem;
+  height: 0.75rem;
+  border: 2px solid var(--ink-200, #ccc);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: nv-spin 0.8s linear infinite;
+}
+@keyframes nv-spin { to { transform: rotate(360deg); } }
+
+@media (prefers-reduced-motion: reduce) {
+  .nv-fallback__spinner { animation: none; }
+}
+</style>

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>