@nutin/cli 2.1.0 → 3.0.0

package/templates/features/markdown/src/app/markdown/components/markdown-landing/markdown-landing.component.test.js.hbs

@@ -0,0 +1,67 @@
+import { Navigation } from '#root/dist/src/core/index.js';
+import { MarkdownLandingComponent } from '#root/dist/src/app/markdown/components/markdown-landing/markdown-landing.component.js';
+
+const PAGES = {
+  a: { slug: 'a', title: 'Page A', description: 'About A' },
+  b: { slug: 'b', title: 'Page B', description: '' },
+};
+const manifest = { getPage: (slug) => PAGES[slug] };
+const pageHref = (slug) => `/docs/${slug}`;
+
+function mount(config) {
+  const target = document.createElement('div');
+  document.body.appendChild(target);
+  const component = new MarkdownLandingComponent(target, { title: 'Docs', description: 'Everything.', manifest, pageHref, ...config });
+  component.render();
+  return component;
+}
+
+const texts = (element, selector) => [...element.querySelectorAll(selector)].map((node) => node.textContent.trim());
+
+describe('MarkdownLandingComponent', () => {
+  it('lists a single hub\'s groups and pages, without repeating its title', () => {
+    const component = mount({ sections: [{ id: 'index', title: 'Docs', description: '', groups: [{ id: 'g', title: 'Basics', pages: ['a', 'b'] }] }] });
+    const element = component.getElement();
+    expect(element.querySelector('.markdown-landing__title').textContent).toBe('Docs');
+    expect(element.querySelector('.markdown-landing__section-title')).toBe(null);
+    expect(texts(element, '.markdown-landing__group-title')).toEqual(['Basics']);
+    expect(texts(element, '.markdown-landing__link')).toEqual(['Page A', 'Page B']);
+    expect(texts(element, '.markdown-landing__page-description')).toEqual(['About A']);
+    component.destroy();
+  });
+
+  it('heads each section when there are several', () => {
+    const component = mount({
+      sections: [
+        { id: 'api', title: 'API', description: 'The API.', pages: ['a'] },
+        { id: 'tools', title: 'Tools', description: '', pages: ['b'] },
+      ],
+    });
+    expect(texts(component.getElement(), '.markdown-landing__section-title')).toEqual(['API', 'Tools']);
+    expect(texts(component.getElement(), '.markdown-landing__section-description')).toEqual(['The API.']);
+    component.destroy();
+  });
+
+  it('links each section to its own landing when sectionHref is set', () => {
+    const component = mount({
+      sections: [{ id: 'api', title: 'API', description: 'The API.', pages: ['a'] }],
+      sectionHref: (id) => `/docs/${id}`,
+    });
+    const links = [...component.getElement().querySelectorAll('.markdown-landing__link')];
+    expect(links.map((a) => a.getAttribute('href'))).toEqual(['/docs/api']);
+    expect(component.getElement().querySelector('.markdown-landing__pages')).toBe(null);
+    component.destroy();
+  });
+
+  it('routes link clicks through the SPA router', () => {
+    const navigateSpy = spyOn(Navigation, 'navigateTo').andCallFake(() => {});
+    const component = mount({ sections: [{ id: 'index', title: 'Docs', description: '', pages: ['a'] }] });
+    try {
+      component.getElement().querySelector('.markdown-landing__link').click();
+    } finally {
+      navigateSpy.restore();
+    }
+    expect(navigateSpy.lastCall[0]).toBe('/docs/a');
+    component.destroy();
+  });
+});

package/templates/features/markdown/src/app/markdown/components/markdown-landing/markdown-landing.component.ts.hbs

@@ -0,0 +1,87 @@
+import { Component, Navigation, html, SafeHtml } from '../../../../core/index.js';
+import { IMarkdownGroup, IMarkdownSection, MarkdownManifest } from '../../markdown-manifest.js';
+
+export interface IMarkdownLandingConfig {
+  title: string;
+  description: string;
+  // Listed with their pages, or as links to their own landing when sectionHref is set.
+  sections: IMarkdownSection[];
+  manifest: MarkdownManifest;
+  pageHref: (slug: string) => string;
+  sectionHref?: (sectionId: string) => string;
+}
+
+// The landing's building blocks, exported so a custom template can reuse them.
+export function renderLandingPages(slugs: string[], config: IMarkdownLandingConfig): SafeHtml {
+  const items = slugs.map((slug) => {
+    const page = config.manifest.getPage(slug);
+    if (!page) return '';
+    return html`
+      <li class="markdown-landing__page">
+        <a href="${config.pageHref(slug)}" class="markdown-landing__link" data-event="click:_navigateTo:@attr:href">${page.title}</a>
+        ${page.description ? html`<p class="markdown-landing__page-description">${page.description}</p>` : ''}
+      </li>
+    `;
+  });
+  return html`<ul class="markdown-landing__pages">${items}</ul>`;
+}
+
+export function renderLandingGroup(group: IMarkdownGroup, config: IMarkdownLandingConfig): SafeHtml {
+  return html`
+    <div class="markdown-landing__group">
+      ${group.title ? html`<h3 class="markdown-landing__group-title">${group.title}</h3>` : ''}
+      ${renderLandingPages(group.pages, config)}
+    </div>
+  `;
+}
+
+// withHeading: false for the only section of a landing, whose title is already the page's.
+export function renderLandingSection(section: IMarkdownSection, config: IMarkdownLandingConfig, withHeading: boolean): SafeHtml {
+  const body = section.groups
+    ? section.groups.map((group) => renderLandingGroup(group, config))
+    : renderLandingPages(section.pages ?? [], config);
+  return html`
+    <section class="markdown-landing__section">
+      ${withHeading ? html`<h2 class="markdown-landing__section-title">${section.title}</h2>` : ''}
+      ${withHeading && section.description ? html`<p class="markdown-landing__section-description">${section.description}</p>` : ''}
+      ${body}
+    </section>
+  `;
+}
+
+export function renderLandingSectionLinks(config: IMarkdownLandingConfig): SafeHtml {
+  const sectionHref = config.sectionHref ?? ((id: string) => id);
+  return html`
+    <ul class="markdown-landing__sections">
+      ${config.sections.map((section) => html`
+        <li class="markdown-landing__section">
+          <a href="${sectionHref(section.id)}" class="markdown-landing__link" data-event="click:_navigateTo:@attr:href">${section.title}</a>
+          ${section.description ? html`<p class="markdown-landing__section-description">${section.description}</p>` : ''}
+        </li>
+      `)}
+    </ul>
+  `;
+}
+
+export const markdownLandingTemplate = (_config: IMarkdownLandingConfig) => html`
+  <div class="markdown-landing__body">
+    <h1 class="markdown-landing__title">${_config.title}</h1>
+    ${_config.description ? html`<p class="markdown-landing__description">${_config.description}</p>` : ''}
+    ${_config.sectionHref
+      ? renderLandingSectionLinks(_config)
+      : _config.sections.map((section) => renderLandingSection(section, _config, _config.sections.length > 1))}
+  </div>
+`;
+
+// The index shown on the bare route of a folder with "landing": its hub(s) and pages.
+export class MarkdownLandingComponent extends Component<HTMLElement, IMarkdownLandingConfig> {
+  // templateFn: your own template, e.g. built from the render helpers above.
+  constructor(mountTarget: HTMLElement, config: IMarkdownLandingConfig, templateFn: (config: IMarkdownLandingConfig) => Nutin.Template = markdownLandingTemplate) {
+    // Mounting replaces the placeholder element, so its class is set here.
+    super({ templateFn, mountTarget, config, props: { className: 'markdown-landing' } });
+  }
+
+  protected _navigateTo(href: string): void {
+    Navigation.navigateTo(href);
+  }
+}

package/templates/features/markdown/src/app/markdown/components/markdown-nav/markdown-nav.component.scss.hbs

@@ -0,0 +1,42 @@
+// :where() keeps these rules at zero specificity: see markdown.view.scss.
+:where(.markdown-nav__container) {
+  flex: 0 0 var(--markdown-nav-width, 16rem);
+}
+
+:where(.markdown-nav ul) {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+:where(.markdown-nav__section + .markdown-nav__section, .markdown-nav__group + .markdown-nav__group) {
+  margin-top: 1rem;
+}
+
+:where(.markdown-nav__section-title, .markdown-nav__group-title) {
+  display: block;
+  font-weight: bold;
+  margin-bottom: 0.25rem;
+}
+
+:where(.markdown-nav__group-title) {
+  font-size: 0.875rem;
+  opacity: 0.75;
+}
+
+:where(.markdown-nav__link) {
+  display: block;
+  padding: 0.25rem 0;
+}
+
+:where(.markdown-nav__link--active) {
+  font-weight: bold;
+}
+
+// Stacked above the content on narrow screens (see markdown.view.scss): the width
+// basis would otherwise become a fixed height.
+@media (max-width: 700px) {
+  :where(.markdown-nav__container) {
+    flex-basis: auto;
+  }
+}

package/templates/features/markdown/src/app/markdown/components/markdown-nav/markdown-nav.component.test.js.hbs

@@ -0,0 +1,59 @@
+import { Navigation, html } from '#root/dist/src/core/index.js';
+import { MarkdownNavComponent, renderNavSection } from '#root/dist/src/app/markdown/components/markdown-nav/markdown-nav.component.js';
+
+const PAGES = { a: { slug: 'a', title: 'Page A' }, b: { slug: 'b', title: 'Page B' } };
+const manifest = { getPage: (slug) => PAGES[slug] };
+
+function mount(config, templateFn) {
+  const target = document.createElement('div');
+  document.body.appendChild(target);
+  const component = new MarkdownNavComponent(target, {
+    sections: [{ id: 'api', title: 'API', groups: [{ id: 'g', title: 'Group', pages: ['a', 'b', 'missing'] }] }],
+    manifest,
+    currentSlug: 'b',
+    pageHref: (slug) => `/docs/api/${slug}`,
+    ...config,
+  }, templateFn);
+  component.render();
+  return component;
+}
+
+describe('MarkdownNavComponent', () => {
+  it('lists sections, group titles and pages, skipping slugs without a page', () => {
+    const component = mount();
+    const element = component.getElement();
+    expect(element.querySelector('.markdown-nav__section-title').textContent).toBe('API');
+    expect(element.querySelector('.markdown-nav__group-title').textContent).toBe('Group');
+    expect([...element.querySelectorAll('.markdown-nav__link')].map((a) => a.getAttribute('href'))).toEqual(['/docs/api/a', '/docs/api/b']);
+    component.destroy();
+  });
+
+  it('marks the current page as active, with aria-current', () => {
+    const component = mount();
+    const active = component.getElement().querySelector('.markdown-nav__link--active');
+    expect(active.textContent).toBe('Page B');
+    expect(active.getAttribute('aria-current')).toBe('page');
+    expect(component.getElement().querySelectorAll('[aria-current]').length).toBe(1);
+    component.destroy();
+  });
+
+  it('routes a link click through the SPA router', () => {
+    const navigateSpy = spyOn(Navigation, 'navigateTo').andCallFake(() => {});
+    const component = mount();
+    try {
+      component.getElement().querySelector('[href="/docs/api/a"]').click();
+    } finally {
+      navigateSpy.restore();
+    }
+    expect(navigateSpy.lastCall[0]).toBe('/docs/api/a');
+    component.destroy();
+  });
+
+  it('accepts its own template, built from the exported render helpers', () => {
+    const component = mount({}, (config) => html`<ul class="my-nav">${config.sections.map((section) => renderNavSection(section, config))}</ul>`);
+    const element = component.getElement();
+    expect(element.querySelector('.my-nav .markdown-nav__section-title').textContent).toBe('API');
+    expect(element.querySelector('nav.markdown-nav')).toBe(null);
+    component.destroy();
+  });
+});

package/templates/features/markdown/src/app/markdown/components/markdown-nav/markdown-nav.component.ts.hbs

@@ -0,0 +1,72 @@
+import { Component, Navigation, html, raw, SafeHtml } from '../../../../core/index.js';
+import { IMarkdownGroup, IMarkdownSection, MarkdownManifest } from '../../markdown-manifest.js';
+import { markdownText } from '../../markdown-i18n.js';
+
+export interface IMarkdownNavConfig {
+  sections: IMarkdownSection[];
+  manifest: MarkdownManifest;
+  currentSlug: string;
+  pageHref: (slug: string) => string;
+}
+
+// The nav's building blocks, exported so a custom template can reuse them.
+// Links route through the component's _navigateTo (data-event).
+export function renderNavLink(slug: string, config: IMarkdownNavConfig): SafeHtml | string {
+  const page = config.manifest.getPage(slug);
+  if (!page) return '';
+
+  const current = slug === config.currentSlug;
+  return html`
+    <li>
+      <a
+        href="${config.pageHref(slug)}"
+        class="markdown-nav__link${current ? ' markdown-nav__link--active' : ''}"
+        ${current ? raw('aria-current="page"') : ''}
+        data-event="click:_navigateTo:@attr:href"
+      >${page.title}</a>
+    </li>
+  `;
+}
+
+export function renderNavGroup(group: IMarkdownGroup, config: IMarkdownNavConfig): SafeHtml {
+  const title = group.title ? html`<span class="markdown-nav__group-title">${group.title}</span>` : '';
+  return html`
+    <li class="markdown-nav__group">
+      ${title}
+      <ul class="markdown-nav__pages">${group.pages.map((slug) => renderNavLink(slug, config))}</ul>
+    </li>
+  `;
+}
+
+export function renderNavSection(section: IMarkdownSection, config: IMarkdownNavConfig): SafeHtml {
+  const items = section.groups
+    ? section.groups.map((group) => renderNavGroup(group, config))
+    : (section.pages ?? []).map((slug) => renderNavLink(slug, config));
+
+  return html`
+    <li class="markdown-nav__section">
+      <span class="markdown-nav__section-title">${section.title}</span>
+      <ul class="markdown-nav__groups">${items}</ul>
+    </li>
+  `;
+}
+
+export const markdownNavTemplate = (_config: IMarkdownNavConfig) => html`
+  <nav class="markdown-nav" aria-label="${markdownText('pages', 'Pages')}">
+    <ul class="markdown-nav__sections">
+      ${_config.sections.map((section) => renderNavSection(section, _config))}
+    </ul>
+  </nav>
+`;
+
+export class MarkdownNavComponent extends Component<HTMLElement, IMarkdownNavConfig> {
+  // templateFn: your own template, e.g. built from the render helpers above.
+  constructor(mountTarget: HTMLElement, config: IMarkdownNavConfig, templateFn: (config: IMarkdownNavConfig) => Nutin.Template = markdownNavTemplate) {
+    // Mounting replaces the placeholder element, so its class is re-applied here.
+    super({ templateFn, mountTarget, config, props: { className: 'markdown-nav__container' } });
+  }
+
+  protected _navigateTo(href: string): void {
+    Navigation.navigateTo(href);
+  }
+}

package/templates/features/markdown/src/app/markdown/locales/en.json.hbs

@@ -0,0 +1,6 @@
+{
+  "pages": "Pages",
+  "onThisPage": "On this page",
+  "empty": "Nothing here yet.",
+  "loadError": "This page couldn't be loaded."
+}

package/templates/features/markdown/src/app/markdown/markdown-guards.test.js.hbs

@@ -0,0 +1,63 @@
+import { MarkdownGuards } from '#root/dist/src/app/markdown/markdown-guards.js';
+import { MarkdownManifestsService } from '#root/dist/src/app/markdown/markdown-manifests.service.js';
+
+const PAGES = { a: { slug: 'a', section: 'api' }, b: { slug: 'b', section: 'tools' } };
+const SECTIONS = { api: { id: 'api' }, tools: { id: 'tools' } };
+
+function fakeManifest({ hasPages = true } = {}) {
+  return {
+    hasPages,
+    firstSlug: hasPages ? 'a' : undefined,
+    getPage: (slug) => (hasPages ? PAGES[slug] : undefined),
+    getSection: (id) => (hasPages ? SECTIONS[id] : undefined),
+  };
+}
+
+describe('MarkdownGuards', () => {
+  let loadSpy;
+  let manifest;
+
+  beforeEach(() => {
+    manifest = fakeManifest();
+    loadSpy = spyOn(MarkdownManifestsService, 'load').andCallFake(() => Promise.resolve(manifest));
+  });
+
+  afterEach(() => {
+    loadSpy.restore();
+  });
+
+  it('pageExists loads the manifest, then allows known slugs and the bare route', async () => {
+    const guard = MarkdownGuards.pageExists('docs');
+    expect(await guard({ slug: 'a' })).toBe(true);
+    expect(await guard({})).toBe(true);
+    expect(loadSpy.lastCall[0]).toBe('docs');
+  });
+
+  it('pageExists sends unknown slugs to /404', async () => {
+    expect(await MarkdownGuards.pageExists('docs')({ slug: 'nope' })).toBe('/404');
+  });
+
+  it('both guards let an empty or failed manifest through, for the empty or error state', async () => {
+    manifest = fakeManifest({ hasPages: false });
+    expect(await MarkdownGuards.pageExists('docs')({ slug: 'a' })).toBe(true);
+    expect(await MarkdownGuards.sectionPageExists('docs')({ section: 'api', slug: 'a' })).toBe(true);
+  });
+
+  it('sectionPageExists allows the bare route, a known section, and a page of that section', async () => {
+    const guard = MarkdownGuards.sectionPageExists('docs');
+    expect(await guard({})).toBe(true);
+    expect(await guard({ section: 'api' })).toBe(true);
+    expect(await guard({ section: 'api', slug: 'a' })).toBe(true);
+  });
+
+  it('sectionPageExists sends a page of another section, or an unknown section, to /404', async () => {
+    const guard = MarkdownGuards.sectionPageExists('docs');
+    expect(await guard({ section: 'api', slug: 'b' })).toBe('/404');
+    expect(await guard({ section: 'nope', slug: 'a' })).toBe('/404');
+    expect(await guard({ section: 'nope' })).toBe('/404');
+  });
+
+  it('sectionPageExists redirects a section-less /<id>/<slug> to the page in its section', async () => {
+    expect(await MarkdownGuards.sectionPageExists('docs')({ section: 'b' })).toBe('/docs/tools/b');
+  });
+});

package/templates/features/markdown/src/app/markdown/markdown-guards.ts.hbs

@@ -0,0 +1,31 @@
+import { MarkdownManifestsService } from './markdown-manifests.service.js';
+
+// Both guards load the source's manifest (once) before the page renders.
+export const MarkdownGuards = {
+  // For '/<id>/:slug?' routes. A bare '/<id>' renders the first page.
+  pageExists: (id: string): Nutin.RouteGuard => {
+    return async (params) => {
+      const manifest = await MarkdownManifestsService.load(id);
+      if (!manifest.hasPages) return true;
+      const slug = params.slug || manifest.firstSlug;
+      return (!!slug && !!manifest.getPage(slug)) || '/404';
+    };
+  },
+
+  // For '/<id>/:section?/:slug?' routes ("sectionInPath: true").
+  // A bare '/<id>/<slug>' redirects to that page's section.
+  sectionPageExists: (id: string): Nutin.RouteGuard => {
+    return async (params) => {
+      const manifest = await MarkdownManifestsService.load(id);
+      if (!manifest.hasPages || !params.section) return true;
+
+      if (manifest.getSection(params.section)) {
+        if (!params.slug) return true;
+        return manifest.getPage(params.slug)?.section === params.section || '/404';
+      }
+
+      const page = !params.slug ? manifest.getPage(params.section) : undefined;
+      return page ? `/${id}/${page.section}/${page.slug}` : '/404';
+    };
+  },
+};

package/templates/features/markdown/src/app/markdown/markdown-i18n.test.js.hbs

@@ -0,0 +1,78 @@
+import nutinConfig from '#root/dist/nutin.config.js';
+import { I18nService } from '#root/dist/src/core/index.js';
+import { markdownLanguage, markdownText, onMarkdownLanguageChange } from '#root/dist/src/app/markdown/markdown-i18n.js';
+
+describe('markdown-i18n', () => {
+  let hadDefine;
+  let savedDefine;
+
+  beforeEach(() => {
+    hadDefine = '__NUTIN_I18N__' in globalThis;
+    savedDefine = globalThis.__NUTIN_I18N__;
+  });
+
+  afterEach(() => {
+    if (hadDefine) globalThis.__NUTIN_I18N__ = savedDefine;
+    else delete globalThis.__NUTIN_I18N__;
+  });
+
+  it('markdownLanguage returns the current language with i18n, null without', () => {
+    globalThis.__NUTIN_I18N__ = true;
+    expect(markdownLanguage()).toBe(I18nService.currentLanguage);
+    globalThis.__NUTIN_I18N__ = false;
+    expect(markdownLanguage()).toBe(null);
+  });
+
+  it('markdownLanguage follows nutin.config.js "i18n" when the builder define is missing', () => {
+    delete globalThis.__NUTIN_I18N__;
+    expect(markdownLanguage()).toBe(nutinConfig.i18n ? I18nService.currentLanguage : null);
+  });
+
+  it('markdownText translates a "markdown." key with i18n, passing the fallback', () => {
+    globalThis.__NUTIN_I18N__ = true;
+    const translateSpy = spyOn(I18nService, 'translate').andCallFake(() => 'Sommaire');
+    try {
+      expect(markdownText('toc', 'Contents')).toBe('Sommaire');
+      expect(translateSpy.lastCall).toEqual(['markdown.toc', 'Contents']);
+    } finally {
+      translateSpy.restore();
+    }
+  });
+
+  it('markdownText returns the fallback without i18n, without translating', () => {
+    globalThis.__NUTIN_I18N__ = false;
+    const translateSpy = spyOn(I18nService, 'translate');
+    try {
+      expect(markdownText('toc', 'Contents')).toBe('Contents');
+      expect(translateSpy.callCount).toBe(0);
+    } finally {
+      translateSpy.restore();
+    }
+  });
+
+  it('onMarkdownLanguageChange subscribes to language changes with i18n and returns their unsubscribe', () => {
+    globalThis.__NUTIN_I18N__ = true;
+    const unsubscribe = () => {};
+    const callback = () => {};
+    const subscribeSpy = spyOn(I18nService, 'onLanguageChange').andCallFake(() => unsubscribe);
+    try {
+      expect(onMarkdownLanguageChange(callback)).toBe(unsubscribe);
+      expect(subscribeSpy.lastCall).toEqual([callback]);
+    } finally {
+      subscribeSpy.restore();
+    }
+  });
+
+  it('onMarkdownLanguageChange returns a no-op without i18n, without subscribing', () => {
+    globalThis.__NUTIN_I18N__ = false;
+    const subscribeSpy = spyOn(I18nService, 'onLanguageChange');
+    try {
+      const unsubscribe = onMarkdownLanguageChange(() => {});
+      expect(typeof unsubscribe).toBe('function');
+      expect(unsubscribe()).toBe(undefined);
+      expect(subscribeSpy.callCount).toBe(0);
+    } finally {
+      subscribeSpy.restore();
+    }
+  });
+});

package/templates/features/markdown/src/app/markdown/markdown-i18n.ts.hbs

@@ -0,0 +1,31 @@
+import nutinConfig from '../../../nutin.config.js';
+import { I18nService } from '../../core/index.js';
+
+// i18n hooks of the markdown feature. Each I18nService use sits behind core's guard
+// (`globalThis.__NUTIN_I18N__` is set by the builder), so bundles without i18n drop it.
+// A block rather than an early return: esbuild only drops a constant-false block.
+
+// The current language, or null without i18n (one manifest per source then).
+export function markdownLanguage(): string | null {
+  if (globalThis.__NUTIN_I18N__ ?? nutinConfig.i18n) {
+    return I18nService.currentLanguage;
+  }
+  return null;
+}
+
+// A UI string from the "markdown" translations (src/app/markdown/locales/<lang>.json),
+// or `fallback` without i18n or without a translation.
+export function markdownText(key: string, fallback: string): string {
+  if (globalThis.__NUTIN_I18N__ ?? nutinConfig.i18n) {
+    return I18nService.translate(`markdown.${key}`, fallback);
+  }
+  return fallback;
+}
+
+// Calls `callback` after each language change; returns the unsubscribe function.
+export function onMarkdownLanguageChange(callback: () => void): () => void {
+  if (globalThis.__NUTIN_I18N__ ?? nutinConfig.i18n) {
+    return I18nService.onLanguageChange(callback);
+  }
+  return () => {};
+}

package/templates/features/markdown/src/app/markdown/markdown-manifest.test.js.hbs

@@ -0,0 +1,98 @@
+import { MarkdownManifest } from '#root/dist/src/app/markdown/markdown-manifest.js';
+
+const MANIFEST = {
+  sections: [
+    { id: 'api', title: 'API', description: '', groups: [{ id: 'views', title: 'Views', pages: ['create-a-view'] }] },
+    { id: 'tools', title: 'Tools', description: '', pages: ['builder'] },
+  ],
+  pages: {
+    'create-a-view': { slug: 'create-a-view', title: 'Create a view', section: 'api' },
+    builder: { slug: 'builder', title: 'Builder', section: 'tools' },
+  },
+};
+
+// Single-language behavior, whatever the project's i18n setting.
+const noLanguage = () => null;
+
+let originalFetch;
+let calls;
+
+function mockFetch(...responses) {
+  calls = [];
+  global.fetch = (url) => {
+    calls.push(url);
+    const response = responses.shift();
+    return Promise.resolve(response);
+  };
+}
+
+const ok = (data) => ({ ok: true, status: 200, json: () => Promise.resolve(data) });
+const notFound = () => ({ ok: false, status: 404, json: () => Promise.reject(new Error('HTTP 404')) });
+
+describe('MarkdownManifest', () => {
+  beforeEach(() => {
+    originalFetch = global.fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it('fetches /generated/<id>.json once, even with concurrent loads', async () => {
+    mockFetch(ok(MANIFEST));
+    const manifest = new MarkdownManifest({ id: 'docs', sectionInPath: true }, noLanguage);
+
+    await Promise.all([manifest.load(), manifest.load()]);
+    await manifest.load();
+
+    expect(calls).toEqual(['/generated/docs.json']);
+    expect(manifest.loaded).toBe(true);
+    expect(manifest.sectionInPath).toBe(true);
+  });
+
+  it('exposes pages and sections', async () => {
+    mockFetch(ok(MANIFEST));
+    const manifest = new MarkdownManifest({ id: 'docs', sectionInPath: true }, noLanguage);
+    await manifest.load();
+
+    expect(manifest.hasPages).toBe(true);
+    expect(manifest.firstSlug).toBe('create-a-view');
+    expect(manifest.firstSlugOf(manifest.getSection('tools'))).toBe('builder');
+    expect(manifest.getPage('builder').title).toBe('Builder');
+    expect(manifest.getPage('nope')).toBeUndefined();
+  });
+
+  it('stays empty and flags loadFailed after a failed load, and retries on the next one', async () => {
+    mockFetch(notFound(), ok(MANIFEST));
+    const manifest = new MarkdownManifest({ id: 'docs', sectionInPath: false }, noLanguage);
+
+    await silenceConsole('error', () => manifest.load());
+    expect(manifest.loaded).toBe(false);
+    expect(manifest.loadFailed).toBe(true);
+    expect(manifest.hasPages).toBe(false);
+    expect(manifest.firstSlug).toBeUndefined();
+
+    await manifest.load();
+    expect(calls.length).toBe(2);
+    expect(manifest.loaded).toBe(true);
+    expect(manifest.loadFailed).toBe(false);
+  });
+
+  it('with a language, fetches /generated/<id>.<lang>.json and reads the current language', async () => {
+    const page = (title) => ({ sections: [{ id: 'index', title: 'x', description: '', pages: ['a'] }], pages: { a: { slug: 'a', title, section: 'index' } } });
+    mockFetch(ok(page('Hello')), ok(page('Bonjour')));
+    let lang = 'en';
+    const manifest = new MarkdownManifest({ id: 'docs', sectionInPath: false }, () => lang);
+
+    await manifest.load();
+    lang = 'fr';
+    expect(manifest.loaded).toBe(false);
+    await manifest.load();
+
+    expect(manifest.getPage('a').title).toBe('Bonjour');
+    lang = 'en';
+    expect(manifest.getPage('a').title).toBe('Hello');
+    await manifest.load();
+    expect(calls).toEqual(['/generated/docs.en.json', '/generated/docs.fr.json']);
+  });
+});