html-builder-web.ts

/**
 * HTML document builder for web preview.
 * Builds a styled page layout with sidebar TOC and main content.
 */

import type { Chapter } from './markdown-processor.js';
import { generateWebStyles } from './styles-web.js';
import type { ResolvedDocConfig } from './config.js';

export interface WebDocMetadata {
  title: string;
  version: string;
  lang: string;
}

function buildSidebarHtml(
  chapters: Chapter[],
  metadata: WebDocMetadata,
  config?: ResolvedDocConfig,
): string {
  const languageLabels = config?.languageLabels ?? {
    en: 'English',
    ko: '한국어',
    ja: '日本語',
    th: 'ภาษาไทย',
  };
  const langLabel = languageLabels[metadata.lang] || metadata.lang;

  const navItems = chapters
    .map((chapter, index) => {
      const num = index + 1;
      const anchorId = chapter.headings[0]?.id || `chapter-${chapter.slug}`;

      const subsections = chapter.headings.filter((h) => h.level === 2);
      let subsectionHtml = '';
      if (subsections.length > 0) {
        const subItems = subsections
          .map((h) => `<li><a href="#${h.id}">${h.text}</a></li>`)
          .join('\n');
        subsectionHtml = `<ul class="toc-subsections">${subItems}</ul>`;
      }

      return `<li><a href="#${anchorId}">${num}. ${chapter.title}</a>${subsectionHtml}</li>`;
    })
    .join('\n');

  // FR-2768 made .doc-sidebar a fixed-height, overflow:hidden flex column
  // and delegated scrolling to an inner .doc-sidebar__scroll element (see
  // styles-web.ts). website-builder.ts emits that wrapper; this legacy
  // single-page preview builder must too, otherwise the nav overflows a
  // clipped container with no scrollport and the sidebar can't scroll.
  // .doc-sidebar-header is display:none in Phase 2, so leaving it outside
  // the scrollport mirrors the pinned version block in website-builder.ts.
  return `
<aside class="doc-sidebar">
  <div class="doc-sidebar-header">
    <h2>${metadata.title}</h2>
    <div class="doc-meta">${metadata.version} &middot; ${langLabel}</div>
  </div>
  <div class="doc-sidebar__scroll">
    <ul class="doc-sidebar-nav">
      ${navItems}
    </ul>
  </div>
</aside>`;
}

function buildContentHtml(chapters: Chapter[]): string {
  return chapters
    .map(
      (chapter) =>
        `<section class="chapter" id="chapter-${chapter.slug}">\n` +
        `${chapter.htmlContent}\n</section>`,
    )
    .join('\n');
}

function buildLiveReloadScript(): string {
  return `
<script>
(function() {
  let lastEtag = '';
  async function poll() {
    try {
      const res = await fetch('/__reload');
      const data = await res.json();
      if (lastEtag && lastEtag !== data.etag) {
        location.reload();
      }
      lastEtag = data.etag;
    } catch {}
    setTimeout(poll, 500);
  }
  poll();

  // Active sidebar link tracking
  const observer = new IntersectionObserver(
    (entries) => {
      for (const entry of entries) {
        if (entry.isIntersecting) {
          const id = entry.target.id;
          document.querySelectorAll('.doc-sidebar-nav a').forEach(a => {
            a.classList.toggle('active', a.getAttribute('href') === '#' + id);
          });
          break;
        }
      }
    },
    { rootMargin: '-10% 0px -80% 0px' }
  );
  document.querySelectorAll('h1[id], h2[id]').forEach(h => observer.observe(h));
})();
</script>`;
}

export function buildWebDocument(
  chapters: Chapter[],
  metadata: WebDocMetadata,
  config?: ResolvedDocConfig,
): string {
  // FR-2726: forward consumer branding tokens to the preview stylesheet
  // so preview renders with the same accent palette as the production
  // build. Skipped silently when `config` is omitted.
  const styles = generateWebStyles(
    metadata.lang,
    config
      ? {
          primaryColor: config.branding.primaryColor,
          primaryColorHover: config.branding.primaryColorHover,
          primaryColorActive: config.branding.primaryColorActive,
          primaryColorSoft: config.branding.primaryColorSoft,
        }
      : undefined,
  );
  const sidebar = buildSidebarHtml(chapters, metadata, config);
  const content = buildContentHtml(chapters);
  const liveReload = buildLiveReloadScript();

  const languageLabels = config?.languageLabels ?? {
    en: 'English',
    ko: '한국어',
    ja: '日本語',
    th: 'ภาษาไทย',
  };

  return `<!DOCTYPE html>
<html lang="${metadata.lang}">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>${metadata.title} - ${languageLabels[metadata.lang] || metadata.lang}</title>
  <style>${styles}</style>
</head>
<body>
<div class="doc-page">
  ${sidebar}
  <main class="doc-main">
    ${content}
  </main>
</div>
${liveReload}
</body>
</html>`;
}