@glossarist/concept-browser 0.7.43 → 0.7.45

package/src/__tests__/non-verbal-cross-ref.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { defineComponent, h } from 'vue';
+import { mount } from '@vue/test-utils';
+import { useNonVerbalCrossRef } from '../composables/use-non-verbal-cross-ref';
+
+const Host = defineComponent({
+  setup() {
+    const { navigateToEntity } = useNonVerbalCrossRef();
+    return { navigateToEntity };
+  },
+  render() {
+    return h('div');
+  },
+});
+
+function setHash(href: string) {
+  // jsdom-compatible history stub
+  Object.defineProperty(window, 'location', {
+    configurable: true,
+    value: { ...window.location, hash: '' },
+  });
+  // Some jsdom builds make location readonly; fall back to defining on the prototype chain.
+  try {
+    window.location.hash = href;
+  } catch {
+    Object.defineProperty(window.location, 'hash', { configurable: true, value: href });
+  }
+}
+
+describe('useNonVerbalCrossRef', () => {
+  let pushSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    pushSpy = vi.spyOn(window.history, 'pushState').mockImplementation(() => undefined);
+    setHash('');
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  function click(target: HTMLElement): void {
+    const ev = new MouseEvent('click', { bubbles: true, cancelable: true });
+    target.dispatchEvent(ev);
+  }
+
+  it('activates the target when a figure anchor link is clicked', async () => {
+    const wrapper = mount(Host, { attachTo: document.body });
+    const figure = document.createElement('figure');
+    figure.id = 'figure-ds-mixed';
+    const scrollSpy = vi.spyOn(figure, 'scrollIntoView').mockImplementation(() => undefined);
+    const focusSpy = vi.spyOn(figure, 'focus').mockImplementation(() => undefined);
+    document.body.appendChild(figure);
+
+    const link = document.createElement('a');
+    link.href = '#figure-ds-mixed';
+    link.textContent = 'Fig 1';
+    document.body.appendChild(link);
+
+    click(link);
+
+    expect(scrollSpy).toHaveBeenCalled();
+    expect(focusSpy).toHaveBeenCalledWith({ preventScroll: true });
+    expect(figure.classList.contains('nv-entity--highlighted')).toBe(true);
+    expect(pushSpy).toHaveBeenCalledWith(null, '', '#figure-ds-mixed');
+
+    document.body.removeChild(figure);
+    document.body.removeChild(link);
+    wrapper.unmount();
+  });
+
+  it('responds to table and formula anchor prefixes', async () => {
+    const wrapper = mount(Host, { attachTo: document.body });
+
+    for (const kind of ['table', 'formula'] as const) {
+      const target = document.createElement('div');
+      target.id = `${kind}-ds-foo`;
+      const scrollSpy = vi.spyOn(target, 'scrollIntoView').mockImplementation(() => undefined);
+      document.body.appendChild(target);
+
+      const link = document.createElement('a');
+      link.href = `#${kind}-ds-foo`;
+      document.body.appendChild(link);
+
+      click(link);
+      expect(scrollSpy).toHaveBeenCalled();
+      vi.mocked(scrollSpy).mockRestore();
+
+      document.body.removeChild(target);
+      document.body.removeChild(link);
+    }
+    wrapper.unmount();
+  });
+
+  it('ignores clicks on links that are not entity anchors', async () => {
+    const wrapper = mount(Host, { attachTo: document.body });
+    const otherEl = document.createElement('div');
+    otherEl.id = 'something-else';
+    const scrollSpy = vi.spyOn(otherEl, 'scrollIntoView').mockImplementation(() => undefined);
+    document.body.appendChild(otherEl);
+
+    const link = document.createElement('a');
+    link.href = '#something-else';
+    document.body.appendChild(link);
+
+    click(link);
+    expect(scrollSpy).not.toHaveBeenCalled();
+    expect(pushSpy).not.toHaveBeenCalled();
+
+    document.body.removeChild(otherEl);
+    document.body.removeChild(link);
+    wrapper.unmount();
+  });
+
+  it('does not activate when the target element is missing', async () => {
+    const wrapper = mount(Host, { attachTo: document.body });
+    const link = document.createElement('a');
+    link.href = '#figure-ds-missing';
+    document.body.appendChild(link);
+
+    expect(() => click(link)).not.toThrow();
+    expect(pushSpy).not.toHaveBeenCalled();
+
+    document.body.removeChild(link);
+    wrapper.unmount();
+  });
+
+  it('navigateToEntity activates a known target programmatically', async () => {
+    const wrapper = mount(Host, { attachTo: document.body });
+    const target = document.createElement('figure');
+    target.id = 'figure-ds-prog';
+    const scrollSpy = vi.spyOn(target, 'scrollIntoView').mockImplementation(() => undefined);
+    document.body.appendChild(target);
+
+    (wrapper.vm as unknown as { navigateToEntity: (id: string) => void })
+      .navigateToEntity('figure-ds-prog');
+
+    expect(scrollSpy).toHaveBeenCalled();
+    expect(target.classList.contains('nv-entity--highlighted')).toBe(true);
+
+    document.body.removeChild(target);
+    wrapper.unmount();
+  });
+});

package/src/__tests__/non-verbal-highlight.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { highlightEntity, scrollToEntity } from '../utils/non-verbal-highlight';
+
+describe('non-verbal-highlight', () => {
+  let el: HTMLElement;
+  let focusSpy: ReturnType<typeof vi.spyOn>;
+  let scrollIntoViewSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    el = document.createElement('div');
+    focusSpy = vi.spyOn(el, 'focus').mockImplementation(() => undefined);
+    scrollIntoViewSpy = vi.spyOn(el, 'scrollIntoView').mockImplementation(() => undefined);
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('adds the highlight class and tabindex', () => {
+    highlightEntity(el);
+    expect(el.classList.contains('nv-entity--highlighted')).toBe(true);
+    expect(el.getAttribute('tabindex')).toBe('-1');
+  });
+
+  it('focuses the element without scrolling', () => {
+    highlightEntity(el);
+    expect(focusSpy).toHaveBeenCalledWith({ preventScroll: true });
+  });
+
+  it('removes the highlight class after the duration', () => {
+    highlightEntity(el);
+    expect(el.classList.contains('nv-entity--highlighted')).toBe(true);
+    vi.advanceTimersByTime(2000);
+    expect(el.classList.contains('nv-entity--highlighted')).toBe(false);
+  });
+
+  it('is a no-op for null target', () => {
+    expect(() => highlightEntity(null)).not.toThrow();
+  });
+
+  it('scrollToEntity uses smooth behavior when smooth=true', () => {
+    scrollToEntity(el, true);
+    expect(scrollIntoViewSpy).toHaveBeenCalledWith({ behavior: 'smooth', block: 'start' });
+  });
+
+  it('scrollToEntity uses auto behavior when smooth=false', () => {
+    scrollToEntity(el, false);
+    expect(scrollIntoViewSpy).toHaveBeenCalledWith({ behavior: 'auto', block: 'start' });
+  });
+
+  it('scrollToEntity is a no-op for null target', () => {
+    expect(() => scrollToEntity(null, true)).not.toThrow();
+  });
+});

package/src/__tests__/non-verbal-kind.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+import {
+  KIND_TO_DIR,
+  KIND_TO_BRIDGE,
+  ALL_KINDS,
+  MENTION_KIND_TO_ENTITY_KIND,
+  entityKindFromMentionKind,
+  kindFromType,
+} from '../adapters/non-verbal/kind';
+
+describe('non-verbal kind dispatch', () => {
+  describe('KIND_TO_DIR', () => {
+    it('maps each kind to its plural directory name', () => {
+      expect(KIND_TO_DIR.figure).toBe('figures');
+      expect(KIND_TO_DIR.table).toBe('tables');
+      expect(KIND_TO_DIR.formula).toBe('formulas');
+    });
+
+    it('is frozen (immutable at runtime)', () => {
+      expect(Object.isFrozen(KIND_TO_DIR)).toBe(true);
+    });
+  });
+
+  describe('ALL_KINDS', () => {
+    it('includes figure, table, formula', () => {
+      expect(ALL_KINDS).toContain('figure');
+      expect(ALL_KINDS).toContain('table');
+      expect(ALL_KINDS).toContain('formula');
+    });
+  });
+
+  describe('KIND_TO_BRIDGE', () => {
+    it('maps every kind to a function', () => {
+      for (const kind of ALL_KINDS) {
+        expect(typeof KIND_TO_BRIDGE[kind]).toBe('function');
+      }
+    });
+  });
+
+  describe('MENTION_KIND_TO_ENTITY_KIND', () => {
+    it('maps parseMention kinds to entity kinds', () => {
+      expect(MENTION_KIND_TO_ENTITY_KIND['fig-ref']).toBe('figure');
+      expect(MENTION_KIND_TO_ENTITY_KIND['table-ref']).toBe('table');
+      expect(MENTION_KIND_TO_ENTITY_KIND['formula-ref']).toBe('formula');
+    });
+  });
+
+  describe('entityKindFromMentionKind', () => {
+    it('returns the entity kind for known mention kinds', () => {
+      expect(entityKindFromMentionKind('fig-ref')).toBe('figure');
+      expect(entityKindFromMentionKind('table-ref')).toBe('table');
+      expect(entityKindFromMentionKind('formula-ref')).toBe('formula');
+    });
+
+    it('returns null for unknown mention kinds', () => {
+      expect(entityKindFromMentionKind('cite-ref')).toBeNull();
+      expect(entityKindFromMentionKind('numeric')).toBeNull();
+      expect(entityKindFromMentionKind('unknown')).toBeNull();
+    });
+  });
+
+  describe('kindFromType', () => {
+    it('accepts gl: prefix', () => {
+      expect(kindFromType('gl:Figure')).toBe('figure');
+      expect(kindFromType('gl:Table')).toBe('table');
+      expect(kindFromType('gl:Formula')).toBe('formula');
+    });
+
+    it('accepts gloss: prefix', () => {
+      expect(kindFromType('gloss:Figure')).toBe('figure');
+    });
+
+    it('returns null for unknown type', () => {
+      expect(kindFromType('gl:Unknown')).toBeNull();
+    });
+  });
+});

package/src/__tests__/non-verbal-list.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { mount } from '@vue/test-utils';
+import NonVerbalList from '../components/non-verbal/NonVerbalList.vue';
+import type { StructuralEntityRef } from '../composables/use-concept-entities';
+
+function makeRef(overrides: Partial<StructuralEntityRef> = {}): StructuralEntityRef {
+  return {
+    kind: 'figure',
+    entityId: 'mixed-reflection',
+    display: null,
+    anchor: 'figure-ds-mixed-reflection',
+    ...overrides,
+  };
+}
+
+describe('NonVerbalList.vue', () => {
+  it('renders nothing when refs is empty', () => {
+    const wrapper = mount(NonVerbalList, { props: { refs: [] } });
+    expect(wrapper.find('.section-label').exists()).toBe(false);
+  });
+
+  it('renders one group per kind', () => {
+    const wrapper = mount(NonVerbalList, {
+      props: {
+        refs: [
+          makeRef({ kind: 'figure', entityId: 'foo', anchor: 'figure-ds-foo' }),
+          makeRef({ kind: 'table', entityId: 'bar', anchor: 'table-ds-bar' }),
+        ],
+      },
+    });
+    expect(wrapper.text()).toContain('Figures');
+    expect(wrapper.text()).toContain('Tables');
+  });
+
+  it('links to the anchor href', () => {
+    const wrapper = mount(NonVerbalList, {
+      props: {
+        refs: [makeRef({ kind: 'figure', entityId: 'mixed', anchor: 'figure-ds-mixed' })],
+      },
+    });
+    const a = wrapper.find('a[href="#figure-ds-mixed"]');
+    expect(a.exists()).toBe(true);
+  });
+
+  it('uses display when present, falls back to entityId', () => {
+    const wrapper = mount(NonVerbalList, {
+      props: {
+        refs: [
+          makeRef({ entityId: 'mixed', display: 'Figure 3', anchor: 'figure-ds-mixed' }),
+          makeRef({ entityId: 'plain', display: null, anchor: 'figure-ds-plain' }),
+        ],
+      },
+    });
+    expect(wrapper.text()).toContain('Figure 3');
+    expect(wrapper.text()).toContain('plain');
+  });
+
+  it('shows the raw ID as a secondary label when display is present', () => {
+    const wrapper = mount(NonVerbalList, {
+      props: {
+        refs: [makeRef({ entityId: 'dispersion-prism', display: 'Figure 3', anchor: 'figure-ds-x' })],
+      },
+    });
+    const item = wrapper.find('.nv-list__id');
+    expect(item.text()).toBe('dispersion-prism');
+  });
+});

package/src/__tests__/non-verbal-rep-display.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { createPinia, setActivePinia } from 'pinia';
+import { createRouter, createMemoryHistory } from 'vue-router';
+import type { NonVerbRep } from 'glossarist';
+import NonVerbalRepDisplay from '../components/NonVerbalRepDisplay.vue';
+import { resetFactory } from '../adapters/factory';
+
+// glossarist-js's published `.d.ts` declares NonVerbRep's constructor with 0
+// args, but the V3 runtime accepts a plain-data initializer. Cast through
+// `unknown` at this boundary. See TODO.figures/19.
+function makeRep(data: Record<string, unknown>): NonVerbRep {
+  return data as unknown as NonVerbRep;
+}
+
+function makeRouter() {
+  return createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', name: 'home', component: { template: '<div/>' } },
+      { path: '/dataset/:registerId/concept/:conceptId', name: 'concept', component: { template: '<div/>' } },
+    ],
+  });
+}
+
+describe('NonVerbalRepDisplay.vue — V3 shape', () => {
+  beforeEach(() => {
+    resetFactory();
+    setActivePinia(createPinia());
+  });
+
+  it('renders nothing when reps is empty', () => {
+    const wrapper = mount(NonVerbalRepDisplay, {
+      props: { reps: [], locale: 'eng', registerId: 'ds' },
+    });
+    expect(wrapper.find('.section-label').exists()).toBe(false);
+  });
+
+  it('renders a figure per rep', () => {
+    const rep = makeRep({
+      type: 'photograph',
+      images: [{ src: 'fig.png', format: 'png' }],
+      alt: { eng: 'A diagram' },
+    });
+    const wrapper = mount(NonVerbalRepDisplay, {
+      props: { reps: [rep], locale: 'eng', registerId: 'ds' },
+    });
+    expect(wrapper.findAll('figure').length).toBe(1);
+    expect(wrapper.text()).toContain('photograph');
+  });
+
+  it('renders the localized caption when present', () => {
+    const rep = makeRep({
+      type: 'photo',
+      caption: { eng: 'Figure 1' },
+    });
+    const wrapper = mount(NonVerbalRepDisplay, {
+      props: { reps: [rep], locale: 'eng', registerId: 'ds' },
+    });
+    expect(wrapper.text()).toContain('Figure 1');
+  });
+
+  it('renders sources when present', async () => {
+    const rep = makeRep({
+      type: 'photo',
+      sources: [
+        {
+          type: 'authoritative',
+          origin: {
+            ref: { source: 'ISO 123' },
+            locality: { type: 'clause', referenceFrom: '1.2' },
+          },
+        },
+      ],
+    });
+    const router = makeRouter();
+    await router.push('/');
+    const wrapper = mount(NonVerbalRepDisplay, {
+      props: { reps: [rep], locale: 'eng', registerId: 'ds' },
+      global: { plugins: [router] },
+    });
+    expect(wrapper.text()).toContain('Sources');
+    expect(wrapper.text()).toContain('ISO 123');
+  });
+});

package/src/__tests__/non-verbal-scroll-guard.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createRouter, createMemoryHistory, type Router } from 'vue-router';
+import { defineComponent, h } from 'vue';
+
+vi.mock('../utils/non-verbal-highlight', () => ({
+  scrollToEntity: vi.fn(),
+  highlightEntity: vi.fn(),
+}));
+
+import { scrollToEntity, highlightEntity } from '../utils/non-verbal-highlight';
+import { installNonVerbalScroll } from '../router/non-verbal-scroll-guard';
+
+const Stub = defineComponent({ render: () => h('div') });
+
+function makeRouter(): Router {
+  return createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', name: 'home', component: Stub },
+      { path: '/concept/:id', name: 'concept', component: Stub },
+    ],
+  });
+}
+
+describe('installNonVerbalScroll', () => {
+  let matchMediaSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.mocked(scrollToEntity).mockClear();
+    vi.mocked(highlightEntity).mockClear();
+    vi.mocked(scrollToEntity).mockImplementation(() => undefined);
+    vi.mocked(highlightEntity).mockImplementation(() => undefined);
+    matchMediaSpy = vi.spyOn(window, 'matchMedia').mockReturnValue({
+      matches: false,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+      media: '',
+      addListener: () => undefined,
+      removeListener: () => undefined,
+      dispatchEvent: () => false,
+      onchange: null,
+    });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('scrolls and highlights when navigating to an entity hash', async () => {
+    const router = makeRouter();
+    installNonVerbalScroll(router);
+
+    const target = document.createElement('figure');
+    target.id = 'figure-ds-foo';
+    document.body.appendChild(target);
+
+    await router.push('/concept/1');
+    await router.push({ path: '/concept/1', hash: '#figure-ds-foo' });
+    await vi.advanceTimersByTimeAsync(100);
+
+    expect(scrollToEntity).toHaveBeenCalledWith(target, true);
+    expect(highlightEntity).toHaveBeenCalledWith(target);
+
+    document.body.removeChild(target);
+  });
+
+  it('passes smooth=false when the user prefers reduced motion', async () => {
+    matchMediaSpy.mockReturnValue({
+      matches: true,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+      media: '',
+      addListener: () => undefined,
+      removeListener: () => undefined,
+      dispatchEvent: () => false,
+      onchange: null,
+    });
+
+    const router = makeRouter();
+    installNonVerbalScroll(router);
+
+    const target = document.createElement('figure');
+    target.id = 'figure-ds-reduced';
+    document.body.appendChild(target);
+
+    await router.push({ path: '/concept/2', hash: '#figure-ds-reduced' });
+    await vi.advanceTimersByTimeAsync(100);
+
+    expect(scrollToEntity).toHaveBeenCalledWith(target, false);
+
+    document.body.removeChild(target);
+  });
+
+  it('ignores hashes that are not entity anchors', async () => {
+    const router = makeRouter();
+    installNonVerbalScroll(router);
+
+    await router.push({ path: '/concept/3', hash: '#some-other-hash' });
+    await vi.advanceTimersByTimeAsync(200);
+
+    expect(scrollToEntity).not.toHaveBeenCalled();
+  });
+
+  it('gives up after the polling timeout if the target never appears', async () => {
+    const router = makeRouter();
+    installNonVerbalScroll(router, { timeoutMs: 60 });
+
+    await router.push({ path: '/concept/4', hash: '#figure-ds-never' });
+    await vi.advanceTimersByTimeAsync(200);
+
+    expect(scrollToEntity).not.toHaveBeenCalled();
+    expect(highlightEntity).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/use-concept-entities.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { Concept } from 'glossarist';
+import { computed } from 'vue';
+import { useConceptEntities } from '../composables/use-concept-entities';
+
+function makeConcept(args: {
+  figures?: unknown[];
+  tables?: unknown[];
+  formulas?: unknown[];
+}): Concept {
+  return Concept.fromJSON({
+    id: '2-1-145',
+    localizations: { eng: { language_code: 'eng' } },
+    figures: args.figures ?? [],
+    tables: args.tables ?? [],
+    formulas: args.formulas ?? [],
+  });
+}
+
+describe('useConceptEntities', () => {
+  it('returns an empty list when the concept has no structural refs', () => {
+    const concept = computed(() => makeConcept({}));
+    const datasetId = computed(() => 'iala-2023');
+    const refs = useConceptEntities(concept, datasetId);
+    expect(refs.value).toEqual([]);
+  });
+
+  it('pulls figure refs from concept.figures', () => {
+    const concept = computed(() => makeConcept({
+      figures: [{ ref: 'mixed-reflection' }],
+    }));
+    const refs = useConceptEntities(concept, computed(() => 'iala-2023'));
+    expect(refs.value).toHaveLength(1);
+    expect(refs.value[0]).toMatchObject({
+      kind: 'figure',
+      entityId: 'mixed-reflection',
+      anchor: 'figure-iala-2023-mixed-reflection',
+    });
+  });
+
+  it('pulls table and formula refs alongside figures', () => {
+    const concept = computed(() => makeConcept({
+      figures: [{ ref: 'fig-1' }],
+      tables: [{ ref: 'tbl-1' }],
+      formulas: [{ ref: 'fml-1' }],
+    }));
+    const refs = useConceptEntities(concept, computed(() => 'ds'));
+    const kinds = refs.value.map(r => r.kind);
+    expect(kinds).toEqual(expect.arrayContaining(['figure', 'table', 'formula']));
+  });
+
+  it('preserves display override', () => {
+    const concept = computed(() => makeConcept({
+      figures: [{ ref: 'dispersion-prism', display: 'Figure 3' }],
+    }));
+    const refs = useConceptEntities(concept, computed(() => 'ds'));
+    expect(refs.value[0].display).toBe('Figure 3');
+  });
+
+  it('sets display to null when no override is provided', () => {
+    const concept = computed(() => makeConcept({
+      figures: [{ ref: 'foo' }],
+    }));
+    const refs = useConceptEntities(concept, computed(() => 'ds'));
+    expect(refs.value[0].display).toBeNull();
+  });
+
+  it('recomputes when datasetId changes', () => {
+    const concept = computed(() => makeConcept({
+      figures: [{ ref: 'foo' }],
+    }));
+    const datasetId = computed(() => 'first');
+    const refs = useConceptEntities(concept, datasetId);
+    expect(refs.value[0].anchor).toBe('figure-first-foo');
+  });
+});

package/src/adapters/bibliography-adapter.ts

@@ -0,0 +1,49 @@
+import { BibliographyData, type BibliographyEntry } from 'glossarist';
+
+export interface BibliographyAdapterOptions {
+  basePath?: string;
+  fetcher?: (url: string) => Promise<Response>;
+}
+
+export class BibliographyAdapter {
+  private data: BibliographyData | null = null;
+  private loaded = false;
+  private readonly basePath: string;
+  private readonly fetcher: (url: string) => Promise<Response>;
+
+  constructor(
+    private readonly datasetId: string,
+    opts: BibliographyAdapterOptions = {},
+  ) {
+    this.basePath = opts.basePath ?? import.meta.env.BASE_URL ?? '/';
+    this.fetcher = opts.fetcher ?? ((url: string) => fetch(url));
+  }
+
+  async load(): Promise<void> {
+    if (this.loaded) return;
+    try {
+      const resp = await this.fetcher(`${this.basePath}data/${this.datasetId}/bibliography.json`);
+      if (resp.ok) {
+        const json = await resp.json();
+        this.data = BibliographyData.fromJSON(json);
+      }
+    } catch {
+      // Honest failure: loaded=true prevents retry storms; findById returns null.
+    } finally {
+      this.loaded = true;
+    }
+  }
+
+  findById(id: string): BibliographyEntry | null {
+    return this.data?.find(id) ?? null;
+  }
+
+  all(): BibliographyEntry[] {
+    return this.data?.entries ?? [];
+  }
+
+  clear(): void {
+    this.data = null;
+    this.loaded = false;
+  }
+}