@glossarist/concept-browser 0.7.44 → 0.7.46

package/src/components/figure/FigureDisplay.vue

@@ -0,0 +1,132 @@
+<script setup lang="ts">
+/**
+ * FigureDisplay — main component for rendering a dataset-level Figure.
+ *
+ * Fetches the entity via the resolver, renders the image(s), caption,
+ * description, and sources. Composite figures (with subfigures) render
+ * recursively — each subfigure is itself a FigureDisplay.
+ *
+ * Self-anchoring: the outer `<figure>` element receives the anchor ID
+ * so `{{fig:id}}` mentions can scroll to it via the cross-ref composable.
+ */
+import { computed, ref } from 'vue';
+import type { Figure } 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 { deriveLayout } from './figure-layout';
+import NonVerbalCaption from '../non-verbal/NonVerbalCaption.vue';
+import NonVerbalSources from '../non-verbal/NonVerbalSources.vue';
+import NonVerbalFallback from '../non-verbal/NonVerbalFallback.vue';
+import FigureImages from './FigureImages.vue';
+
+const props = defineProps<{
+  datasetId: string;
+  entityId: string;
+  locale: string;
+  /** Languages configured on the dataset — drives fallback chain. */
+  datasetLocales?: readonly string[];
+}>();
+
+const k = () => 'figure' as const;
+const ds = () => props.datasetId;
+const id = () => props.entityId;
+const { entity, state, error } = useNonVerbalEntity(k, ds, id);
+
+const fallbackChain = computed(() => resolveFallbackChain(props.datasetLocales));
+const layout = computed(() => entity.value ? deriveLayout(entity.value as Figure) : 'single');
+const anchor = computed(() => anchorId('figure', props.datasetId, props.entityId));
+const descriptionId = computed(() => `${anchor.value}-desc`);
+
+const topLevelImages = computed(() => (entity.value as Figure | null)?.images ?? []);
+</script>
+
+<template>
+  <figure
+    v-if="entity && state === 'loaded'"
+    :id="anchor"
+    :class="`figure figure--${layout}`"
+  >
+    <div v-if="topLevelImages.length" :class="`figure__media figure__media--${layout}`">
+      <FigureImages
+        :images="topLevelImages"
+        :alt="(entity as Figure).alt"
+        :dataset-id="datasetId"
+        :locale="locale"
+        :fallback-chain="fallbackChain"
+        :hasDescription="!!(entity as Figure).description && Object.keys((entity as Figure).description ?? {}).length > 0"
+        :description-id="descriptionId"
+        entity-label="Figure"
+      />
+    </div>
+
+    <template v-if="(entity as Figure).subfigures?.length">
+      <div :class="`figure__subfigures figure__subfigures--${layout}`">
+        <FigureDisplay
+          v-for="sub in (entity as Figure).subfigures"
+          :key="sub.id"
+          :dataset-id="datasetId"
+          :entity-id="sub.id"
+          :locale="locale"
+          :dataset-locales="datasetLocales"
+        />
+      </div>
+    </template>
+
+    <NonVerbalCaption
+      :identifier="(entity as Figure).identifier"
+      :caption="(entity as Figure).caption"
+      :description="(entity as Figure).description"
+      :locale="locale"
+      :fallback-chain="fallbackChain"
+      :description-id="descriptionId"
+    />
+
+    <NonVerbalSources
+      v-if="(entity as Figure).sources?.length"
+      :sources="(entity as Figure).sources!"
+    />
+  </figure>
+
+  <NonVerbalFallback
+    v-else-if="state === 'loading' || state === 'not-found' || state === 'error'"
+    :state="state"
+    kind="figure"
+    :entity-id="entityId"
+    :message="error ?? undefined"
+  />
+</template>
+
+<style scoped>
+.figure {
+  margin: 1rem 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.figure__media--row,
+.figure__media--grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: 0.75rem;
+}
+.figure__media--column {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+.figure__subfigures--row { flex-direction: row; flex-wrap: wrap; gap: 0.75rem; }
+.figure__subfigures--column { flex-direction: column; gap: 0.75rem; }
+.figure__subfigures--grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: 0.75rem;
+}
+
+[dir='rtl'] .figure__subfigures--row { flex-direction: row-reverse; }
+
+.figure:focus-visible {
+  outline: 2px solid var(--blue-500, #3b82f6);
+  outline-offset: 4px;
+}
+</style>

package/src/components/figure/FigureImages.vue

@@ -0,0 +1,111 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import type { FigureImage, LocalizedString } from '../../adapters/non-verbal/types';
+import { pickLocaleText, hasLocale } from '../../utils/locale';
+import { getFactory } from '../../adapters/factory';
+
+const props = withDefaults(defineProps<{
+  images: FigureImage[];
+  alt?: LocalizedString;
+  datasetId: string;
+  locale: string;
+  fallbackChain?: readonly string[];
+  descriptionId?: string;
+  hasDescription?: boolean;
+  entityLabel?: string;
+}>(), {
+  entityLabel: 'Figure',
+});
+
+const resolver = getFactory().nonVerbalResolver;
+
+const altText = computed(() => pickLocaleText(props.alt, props.locale, props.fallbackChain));
+const altMissing = computed(() => !props.alt || Object.keys(props.alt).length === 0);
+const altEmpty = computed(() =>
+  !!props.alt && hasLocale(props.alt, props.locale) && props.alt[props.locale] === '',
+);
+
+interface SourceVariant { src: string; type: string; media?: string; }
+
+const sourceVariants = computed<SourceVariant[]>(() => {
+  const out: SourceVariant[] = [];
+  for (const img of props.images) {
+    if (!img.role || img.role === 'vector' || img.role === 'raster') continue;
+    const src = resolver.resolveImageUrl(props.datasetId, img.src);
+    const type = img.format === 'svg' ? 'image/svg+xml' : `image/${img.format === 'jpg' ? 'jpeg' : img.format}`;
+    let media: string | undefined;
+    if (img.role === 'dark') media = '(prefers-color-scheme: dark)';
+    else if (img.role === 'light') media = '(prefers-color-scheme: light)';
+    else if (img.role === 'print') media = 'print';
+    out.push({ src, type, media });
+  }
+  return out;
+});
+
+const defaultImg = computed(() => {
+  const nonRole = props.images.find(i => !i.role || i.role === 'vector' || i.role === 'raster');
+  const chosen = nonRole ?? props.images[0];
+  if (!chosen) return null;
+  return {
+    src: resolver.resolveImageUrl(props.datasetId, chosen.src),
+    width: chosen.width,
+    height: chosen.height,
+  };
+});
+</script>
+
+<template>
+  <div class="figure__images">
+    <picture v-if="!altMissing">
+      <source
+        v-for="(v, i) in sourceVariants"
+        :key="i"
+        :type="v.type"
+        :srcset="v.src"
+        :media="v.media"
+      />
+      <img
+        v-if="defaultImg"
+        :src="defaultImg.src"
+        :alt="altEmpty ? '' : altText"
+        :width="defaultImg.width"
+        :height="defaultImg.height"
+        loading="lazy"
+        :aria-describedby="hasDescription && descriptionId ? descriptionId : undefined"
+        class="figure__img"
+      >
+    </picture>
+    <div
+      v-else
+      class="figure__alt-missing"
+      role="img"
+      :aria-label="`${entityLabel} is missing alt text`"
+    >
+      <p>{{ entityLabel }}: alt text missing</p>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.figure__images {
+  margin: 0;
+}
+.figure__img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  border-radius: 0.375rem;
+}
+.figure__alt-missing {
+  padding: 1rem;
+  background: #fef3c7;
+  border: 1px dashed #d97706;
+  border-radius: 0.375rem;
+  color: #92400e;
+  font-size: 0.8125rem;
+}
+
+@media (prefers-color-scheme: dark) {
+  .figure__img { background: var(--surface-alt, #222); }
+}
+</style>

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>